Skip to content

README-CN.md

Latest commit

 

History

History
271 lines (206 loc) · 13.6 KB

README-CN.md

File metadata and controls

271 lines (206 loc) · 13.6 KB
Raw

Team First Development

CI

English

Team First Development（TFD）是一套选择性使用的 Codex 团队开发方法。它通过 目标对齐、模型与职责匹配、聚焦上下文和独立审核，改善一个边界明确的开发结果。

当前源码版本为 3.5.0。是否已发布以 v3.5.0 标签和 GitHub Release 为准； 本地检出本身不能证明已经安装、部署或发布。

使用

显式调用唯一的 Skill：

Use tfd:using-tfd to complete this development task.

TFD 首先判断协作收益是否高于协调成本。简单任务由单 Agent 完成，不读取或写入 .tfd/。当任务包含可分离的专业职责，或风险确实要求独立审核时，才考虑使用 项目已配置的团队。

Coordinator workstream

对于 TEAM，Coordinator 在激活成员前把有界目标拆成最少且有用的 workstream。精确确认方案必须展示每个 workstream 的责任成员、验收条件、写入 范围、依赖、交接，以及并行或串行顺序。

只有 Coordinator 可以激活成员；成员不能继续委派，也不能创建未经确认的辅助 Agent。只有无依赖且写入范围不重叠的 workstream 才可并行；BLOCKER 会停止 下游，Coordinator 最后把已接受的产出整合成一个不可变审核候选。

AUTO_REVIEW 模式

默认仍是人工确认。用户显式选择 AUTO_REVIEW 后，只需先确认一个会话级 Autonomy Envelope，其中列明范围、Roster、workstream、可自动审核的 Gate、有界修复 策略、证据要求和精确外部目标。当前 Coordinator 随即成为 Orchestrator，自动审核 并通过每个 Envelope 内 Gate，不再等待用户逐次回复。只有风险或 Envelope 要求时 才调用独立 reviewer；reviewer 提供证据，Orchestrator 才是审批权威。

只有证据充分的 Orchestrator PASS 会推进。BLOCKER 可以进入 Envelope 内的 有界修复循环，UNVERIFIED 可以触发已列明的补证，但都不能直接释放下游。Envelope 可以预先授权精确 commit、non-force merge、branch/tag-ref push、tag、Release、本地 first install/reinstall 和 non-production deployment。production deployment、破坏性 或 force 操作、付费资源、提权、外部消息、安全或身份变更、用户验收、扩大范围， 以及修改 Envelope/Orchestrator，始终只能由用户确认；宿主或平台确认也不能绕过。

未来才产生的 candidate、commit、tag、Release、artifact、install 和 deployment 值， 必须用 late-bound 引用绑定到一个命名 Gate 输出。Orchestrator 在下游 Gate 前冻结完整 digest/OID 并校验 lineage，因此一次确认即可驱动完整链路，不会依赖可漂移的 latest，也不必在每个产物出现后再次询问。有界修复会作废并重算全部下游派生输出。

工程合同

凡是修改源码或软件架构的任务，TFD 都必须在最终确定 PLAN 前完整读取 references/engineering-constraints.md。 这个要求同时适用于 SOLO 和团队执行。规则保持不变；证据深度按风险缩放。

该 reference 是唯一规范副本。计划只识别相关改动形状，执行只携带适用约束， review 检查完整候选；不增加第二个 Skill 或策略引擎。

项目团队

项目创建时可以定义可复用的团队和成员资料：

.tfd/
├── manifest.yaml
├── product-team/
│   ├── team.yaml
│   ├── members/
│   │   ├── alice.yaml
│   │   └── bob.yaml
│   ├── receipts/                 # Wiki 初始化前的旧回执
│   └── wiki/
│       ├── schema.md
│       ├── raw/
│       ├── pages/
│       ├── queries/
│       ├── activity/
│       ├── index.md
│       └── log.md
└── platform-team/
    ├── team.yaml
    └── members/
        └── tingting.yaml

manifest.yaml 只索引团队目录。每个 team.yaml 保存团队名称、用途、成员 ID， 以及可选的 trace: delivery_receipt 策略。每位成员都有一个以人物名字命名的 members/<name>.yaml：

display_name: Alice
responsibility: Implement the agreed product scope
expected_output: A runnable and verified result
agency_role: backend-architect
runtime: codex_thread
model: gpt-5.3-codex-spark
reasoning_effort: high
skills: []

agency_role 是可选的冻结方法来源，与 Runtime 和模型相互独立。TFD 不安装或 运行 agency-agents，不同步人物卡，也不批量导入角色。skills 可以为空；列出 的每个 Skill 都必须以精确名称安装在本地。

Runtime 执行入口 用户可见行为
codex_spawn spawn_agent 当前任务内的子 Agent
codex_thread Codex thread/App Server 侧边栏可见的独立任务
codex_exec codex exec 一次性 CLI 运行

新建或修改成员资料时必须填写 runtime。v3.1 资料缺少 runtime 时解析为 codex_spawn，TFD 必须在激活方案中展示该结果，且不自动改写资料。

项目创建只起草团队资料，不创建 Agent。每个开发需求最多选择一个已配置团队， 再从中选择覆盖计划所需的最小成员子集。经常需要的跨职能组合应单独配置成一个 团队。

团队确认

写入团队资料或创建任何 Agent 前，TFD 必须先展示精确团队方案：目标与范围、 团队标识与用途、每位成员的 ID、显示名称、职责和预期产出、精确模型与 Skills、 可选 agency_role、精确 Runtime、reasoning_effort（或默认值）、资格证据与 来源、用户可见行为、最小激活成员子集与独立 reviewer，以及本次动作是写资料、 激活成员，还是两者都做。

笼统的“组建团队”、沉默、时间紧迫或允许 TFD 自行选择，都不等于确认用户尚未 看过的名单。TFD 必须等待明确确认。若同一份方案同时写明资料写入和立即激活， 一次确认即可覆盖两项动作。任何提案字段发生实质变化都必须重新确认，包括目标、 验收条件、范围、排除项、动作模式、团队标识或用途、成员身份、职责、产出、模型、 Runtime、reasoning effort、Skill、激活子集或 reviewer。

仅配置资料时，TFD 只写入已确认的 profiles，然后停止，不创建 Agent。

codex_spawn 在当前任务内创建子 Agent；codex_thread 创建侧边栏可见的独立 Codex 任务；codex_exec 创建一次性 CLI 运行。

models_cache.json 只用于发现账户候选模型，不证明某个 Runtime 当前可执行该模型。 TFD 还要在所选执行入口检查资格，并要求每个 Skill 以精确名称安装在本机。 确认后只按指定的 runtime + model + reasoning_effort 启动一次；缺少可信运行元数据 时保留 UNVERIFIED，启动失败或不匹配不能成为成功交付。TFD 不自动重试、切换 Runtime、替换模型、降低 reasoning effort 或采用其他静默降级。

完整最小示例见 plugins/tfd/examples/project-tfd。

团队知识库

每个已配置团队可以在自己的目录下拥有一个 Git 原生 Markdown Wiki。团队目录被 移动或归档时，Wiki 会一起保留。LLM Wiki 分为三层：

  1. raw/ 按完整摘要保存不可变来源快照；
  2. pages/ 和 index.md 保存带来源引用、相互链接的维护知识；
  3. log.md、queries/ 和 activity/ 保存知识变更、明确提问和有限工作里程碑 的追加式审计。

它不是通用 RAG，也不会恢复任务控制平面。V1 没有 embedding、向量数据库、 daemon、远程存储、进度状态或恢复权威。可以把 Obsidian 当作可选 Markdown 阅读器，但它没有运行时或写入权威。

知识确认

人工模式下，初始化、摄取、修复、冲突解决和 schema 变更都遵循 PROPOSE -> CONFIRM -> APPLY。已确认 AUTO_REVIEW Envelope 时，初始化和常规 add-only ingest 可以用 Guard 校验加 Orchestrator PASS 代替逐次人工确认；修复、 冲突解决和 schema 变更仍只能由用户确认。在取得其中一种授权前，wiki/ 下任何 文件都不能变化。TFD 展示团队、来源与摘要、页面差异、冲突、index/log 影响、 当前 Wiki baseline、完整 SHA-256 和 12 字符指纹。自然语言确认可以引用短指纹， 但 Guard 只接受完整匹配摘要。提案或 proposal-local Wiki baseline 的实质变化， 在人工模式下需要重新确认；仍在 Envelope 内的 initialization 或常规 add-only ingest 则要重新通过 Guard 并取得绑定新摘要的 Orchestrator PASS。只要混入 conflict、repair、schema 或其他 human-only effect，整个提案都回到人工确认。Envelope 字段变化始终要用户确认。

来源只增不改。新版本创建新的摘要寻址快照，绝不覆盖旧版本。相互冲突且都有 来源的结论保留在 disputed 页面，直到用户单独确认解决方案。

提问与工作审计

用户向团队明确提问，或成员在已授权任务中明确查询 Wiki，只授权记录该问题、 最终答案、引用、提问者和读取时的 Wiki baseline，不需要第二次确认。已确认 执行同样只授权 work_started、关键 handoff、证据约束的 review、最终 delivery 和显式补录。两种例外都不能自动把内容提升为维护知识。

Guard 会按 team.yaml 校验操作者和入选成员 ID，但 V1 没有持久化执行令牌，也不 提供恶意共享主机隔离。符合规范的 Skill 调用仍是确认边界；外部进程竞态替换目录 不在 V1 范围内，并保持 UNVERIFIED。

默认长记录阈值是 1,000 个 Unicode 字符。1,000 字符的答案完整保留在 log.md；1,001 字符的答案写入 queries/，日志只留摘要、引用、详情摘要和 链接。长工作事件按完整允许记录的长度写入 activity/，其简洁摘要本身不能 超过阈值。prompt、隐藏推理、完整 Agent 对话和原始工具输出永远不能成为审计 内容。

如果回答或真实工作成功，但审计追加失败，TFD 分别报告结果和审计失败；不会 回滚成功工作，也不会谎报记录成功。

Lint 与规模边界

只读 lint 检查目录结构、链接、来源、不可变来源历史、日志哈希链和 Git 已提交 前缀、详情记录、跨团队引用、未解决争议以及明显凭据。它绝不自动修复。

V1 的规划规模约为 100 份来源快照和数百个页面。只有实际出现已知内容查询失败、 索引维护成本明显，或语料规模已无法做有界页面选择时，才单独设计搜索升级； 不能只因文件数量就自动引入搜索系统。

本地 Guard 命令

在 plugins/tfd 下使用 Python 3.10 或更高版本运行。使用 - 时，提案和记录 JSON 从标准输入传入：

python3 -m scripts.tfd_wiki.cli init --project-root PROJECT --team-id TEAM --actor-type user --actor-id user --at UTC
python3 -m scripts.tfd_wiki.cli validate --project-root PROJECT --team-id TEAM --proposal -
python3 -m scripts.tfd_wiki.cli apply --project-root PROJECT --team-id TEAM --proposal - --approval-digest SHA256
python3 -m scripts.tfd_wiki.cli record-query --project-root PROJECT --team-id TEAM --record -
python3 -m scripts.tfd_wiki.cli record-activity --project-root PROJECT --team-id TEAM --record -
python3 -m scripts.tfd_wiki.cli lint --project-root PROJECT --team-id TEAM

交付痕迹

团队初始化 Wiki 前，trace: delivery_receipt 继续使用旧的一次性回执。 Wiki 存在后，最终交付只记录一个 delivery activity，不再创建重复回执。

回执和 Wiki activity 都只是工作痕迹，不是运行时权威或可恢复状态；都不会 恢复任务数据库、进度状态、恢复系统或管理控制平面。

授权边界

人工团队确认只授权方案中列明的本地资料写入和/或成员激活，不授权安装、合并、 推送、打标签、发布、部署、对外消息、破坏性清理、特权命令、付费动作或扩大 范围。AUTO_REVIEW 只能预授权已确认 Envelope 定义的精确内部与外部 Gate 和目标； Orchestrator 随后无需用户再次回复即可完成 TFD 审批。其他动作继续保留人工审批边界。

本地检出目录中的版本号本身不能证明已经安装或部署。请以 v3.5.0 标签和 GitHub Release 作为发布证据。

仓库结构

plugins/tfd/.codex-plugin/plugin.json      插件清单
plugins/tfd/skills/using-tfd/SKILL.md      唯一用户 Skill
plugins/tfd/skills/using-tfd/references/auto-review.md
                                           按需加载的 AUTO_REVIEW 协议
plugins/tfd/skills/using-tfd/references/engineering-constraints.md
                                           按需加载的工程合同
plugins/tfd/skills/using-tfd/references/team-wiki.md
                                           按需加载的 Team Wiki 协议
plugins/tfd/scripts/tfd_wiki/              标准库 Wiki Guard
plugins/tfd/examples/project-tfd/          最小 YAML 团队示例
scripts/test_plugin_contract.py            包结构契约

本地验证

测试需要 Python 3.10 或更高版本以及 PyYAML。

python3 -m pip install -r requirements.txt
python3 -m unittest discover -s scripts -p 'test_*.py' -v
cd plugins/tfd
python3 -m unittest discover -s scripts -p 'test_*.py' -v

许可证

MIT