Agent-Squad/PROJECT.md

Agent-Squad 项目事实

工作规则见 AGENTS.md。此文件维护本项目事实，不复制通用规范。

仓库与操作

• 目标/产品边界：通用智能体小队编排底座。角色、蓝图、规划、执行引擎、黑板、HITL 与 HTTP/CLI 组合根。不含预设医疗器械角色或任务模板。不实现 Agent。
• 源码、资产、文档、机器契约位置：Go 模块路径 agent-squad。包为 squad、store、server、cli、textextract、conformance。人类文档在根 README.md、policy/；过程记录在 docs/records/。对外 HTTP 错误合同以错误码库信封为准。
• 权威远端、集成基线、受保护分支：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git，集成基线 main。
• 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。跨仓共同起点是本仓提交加上它锁定的 Agent-Native、错误码库、日志库与规范库 SHA。
• 发布线与批准版本/实际制品查询入口：无独立制品库。可执行文件由 go build 从固定 gitlink 组合产出。
• 提交/审核/合并/发布身份与权限：仓库所有者 weichen。
• 任务唯一来源：Gitea weichen/Agent-Squad 的 Issue 与 Pull Request。
• 规范性文档目录：policy/。
• 过程文档仓/目录：任务卡与交付证据在 .task/（模板 .task/templates/task-card.md）；其他过程记录在 docs/records/（项目内豁免，见采纳记录）。
• 交接记录位置：随任务主记录；需要落盘的任务交接与交付证据放入 .task/，其他落盘交接放入 docs/records/。
• 凭证查找入口及所需字段：LLM 使用环境变量 AGENT_SQUAD_LLM_BASE_URL、AGENT_SQUAD_LLM_API_KEY、AGENT_SQUAD_LLM_MODEL。日志采集 token 使用日志库自己的配置。文档与仓库不记录这些值。

依赖组合

逻辑 ID	路径	角色
agent-native	deps/agent-native	build-required
agent-intent	deps/agent-intent	build-required，可选意图闸门（squadintent 适配器；未配置意图时行为与原实现一致）
development-guidelines	deps/development-guidelines	development-only
error-code-system	deps/error-code-system	build-required
logging-system	deps/logging-system	build-required

go.mod 的 replace 都指向 ./deps/。嵌套在 deps/agent-native/deps/、deps/agent-intent/deps/ 里的同名副本不参与本仓编译，提交必须与本仓 gitlink 一致（scripts/submodule-consistency.sh）。

同一 run 的临界区在 unix 上额外持有 runs/<id>/.lock 的 flock，拿不到锁时返回 ErrRunBusy。非 unix 平台没有这把文件锁，只保留进程内互斥。

克隆：

git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Squad.git
# 已克隆时：git submodule update --init --recursive

验证命令

影响	工作目录与真实命令/CI	前提与不覆盖范围
文档	人工核对入口与相对链接	不证明运行时行为
模块/接口	仓库根：GOWORK=off go vet ./... && GOWORK=off go test -count=1 ./...	需要已初始化的 Agent-Native 子模块；默认 stub，不调用真实模型
数据/权限/恢复	conformance 与 store 测试覆盖运行落盘、HITL 恢复	无共享数据库
UI/执行后端	GOWORK=off go test -count=1 ./server/... ./conformance/...	不覆盖浏览器；SSE 由测试客户端验证
治理与 Agent 执行配置	仓库根：scripts/agent-exec validate --repo . 与 scripts/dm governance check --repo .	需 deps/development-manager 已按 gitlink 检出（首次 dm 调用会构建 dm-server）；只核验 AGENT-EXECUTION.md 与治理文件，不证明实施单元正确

环境与数据

环境/实例 ID	只读查询入口	授权写入入口	DB/存储归属	恢复入口
本地开发	go test 与 CLI runs inspect	CLI / POST /v1/runs 写入调用方指定数据目录	运行目录 <data>/runs/<run_id>/，无共享 DB	进程重启后 POST /v1/runs/{id}/resume，磁盘为权威

共享项及 ACL：无。部署、迁移、发布的审批依据与负责角色：库本身不部署；agent-squad serve 仅作本地组合根，合并进 main 由仓库所有者批准。 实际制品/配置/schema 的查询方法：以当前 main 的 squad 模型与 HTTP 路由为准。