AG AI Factory

AG AI Factory 是一个 Node.js 原生、npm 分发、中央状态化的 Agent 工程工厂。用户在业务项目中直接描述需求、缺陷、Review、发布或架构目标；已安装的平台入口声明自动路由协议，aga CLI 负责中央工作项、Loop、评估、Dashboard 与平台生命周期。

核心结论

• 运行时只要求 Node.js 20+，不发现、下载或执行 Python。
• 正常使用不需要拉取工厂源码；正式发布后执行 npm install -g ag-ai-factory 即可。
• 工厂状态统一位于 AGA_HOME，默认是用户目录下的 .ag-ai-factory。
• init、project link、feature、bug、loop、eval、dashboard 和平台生命周期默认不向业务仓库写任何工厂文件。
• 业务仓库只保留真实业务代码改动；工作项、审查、验证记录、运行状态和评估证据均在中央目录。
• 新工作项使用结构化 verification.json 记录 red/green/regression/exception，并由工作流、Loop 和 Dashboard 共享同一门禁结果。
• 注册表描述 33 个平台的分发兼容性；Codex、Claude Code、TRAE 完成了 Tier 1 用户入口与生命周期契约验证。0.7.0 已在 Codex 与 TRAE 真实会话验证自然语言路由；Claude Code 因当前没有可用客户端，只声明契约验证，不声明真实会话通过。其余平台按自身能力使用用户级 Skill、Rule 或显式 CLI。

安装

正式 npm 包发布后：

npm install -g ag-ai-factory
aga --version
aga doctor --json

本地验证 tarball：

npm test
npm run pack:check
npm pack
npm install -g ./ag-ai-factory-0.9.0.tgz
aga --version

不需要手工配置 Python，也不需要把源码仓库加入 PATH。如果机器曾安装旧版仓库包装命令，先运行 where aga（Windows）或 command -v -a aga（macOS/Linux）；只有当输出仍指向旧源码目录时，才移除那个旧 PATH 项或旧包装文件。npm 自己安装的入口交给 npm uninstall -g ag-ai-factory 管理。

第一次使用

安装需要的平台用户级入口：

aga setup --platform codex --platform claude --platform trae

安装所有具备用户级入口的注册平台：

aga setup --all-user-platforms

批量安装会先预检全部用户级平台，任何冲突都会在写入前停止。Claude Code 已有的 ~/.claude/settings.json 不会被覆盖；安装器只合并 AGA Hook，卸载时也只移除该 Hook，保留 env 等用户设置。

预览并卸载所有受管的用户级平台入口：

aga platform uninstall --all-user-platforms --dry-run
aga platform uninstall --all-user-platforms

卸载只删除 receipt 证明仍未漂移的受管文件；用户修改过的文件会保留。它不会删除中央 AGA_HOME，也不会代替 npm uninstall -g ag-ai-factory。

npm 包必须使用 npm install -g ag-ai-factory@latest 升级；aga factory update 不是 npm 自升级命令。升级后运行 aga platform update --platform <id> 并重启对应工具。npm 升级只替换 CLI，旧 Skill/Rule 会由 doctor 标记为 update_required，不会被静默当作最新入口。

在业务项目目录登记项目。登记只保存源码路径，不修改该目录：

aga init --project-key mall-order --project-name 商城订单系统 --source-root .
aga project resolve --json
aga doctor --platform codex --workspace . --json

之后可以在受支持的 Agent 中直接说“新增订单取消能力”“修复登录超时”“Review 当前改动”。用户不必先输入 $aga；aga Skill 是自动路由入口，也是需要时可显式调用的入口。显示 /aga 只证明入口已发现，若没有中央工作项，应使用上面的组合诊断确认 Agent 是否真正执行了路由协议。

中央状态模型

默认目录结构：

~/.ag-ai-factory/
├─ config.json
├─ projects/
│  ├─ registry.json
│  └─ <project-key>/
│     ├─ profile.json
│     ├─ config.json
│     ├─ work-items/
│     └─ tasks/
│        ├─ dropbox/
│        ├─ inbox/
│        ├─ drafts/
│        ├─ archive/
│        ├─ quarantine/
│        ├─ receipts/
│        └─ ingestion-runs/
├─ runs/
├─ evaluations/
├─ releases/
├─ tasks/
├─ workspaces/
├─ receipts/
├─ locks/
└─ migrations/

设置自定义位置时必须使用绝对路径：

set AGA_HOME=D:\AGFactoryData

常用命令

aga project list --json
aga project select mall-order
aga config show --project-key mall-order
aga config baseline show --project-key mall-order
aga config baseline set --project-key mall-order --id node-tests --executable node --argv-json '["--test"]' --timeout-seconds 900

aga feature --project-key mall-order --risk-level L2 FEAT-2026-001 用户权限管理
aga bug --project-key mall-order --risk-level L2 BUG-2026-001 登录超时

aga artifact list --project-key mall-order --work-id FEAT-2026-001
aga artifact get --project-key mall-order --work-id FEAT-2026-001 --name feat-需求规格.md
aga context FEAT-2026-001 prepare --project-key mall-order
aga verification status --project-key mall-order --work-id FEAT-2026-001 --json
aga verification plan --project-key mall-order --work-id FEAT-2026-001 --strategy test-first --reason "Node tests" --source lib --test test
aga verification run --project-key mall-order --work-id FEAT-2026-001 --type red --executable node --arg=--test --timeout-seconds 900 --json
aga workflow FEAT-2026-001 prepare-complete --project-key mall-order

aga workspace plan --project-key mall-order --work-id FEAT-2026-001 --provider current --json
aga workspace plan --project-key mall-order --work-id FEAT-2026-001 --provider git-worktree --json
aga workspace create --project-key mall-order --work-id FEAT-2026-001 --owner codex-session-01 --json
aga workspace create --project-key mall-order --work-id FEAT-2026-001 --owner codex-session-01 --yes --json
aga workspace adopt --workspace . --work-id FEAT-2026-001 --owner codex-session-01 --yes --json
aga workspace renew --project-key mall-order --work-id FEAT-2026-001 --owner codex-session-01 --yes --json
aga workspace cleanup --project-key mall-order --work-id FEAT-2026-001 --owner codex-session-01 --json
aga workspace cleanup --project-key mall-order --work-id FEAT-2026-001 --owner codex-session-01 --yes --json
aga workspace status --project-key mall-order --work-id FEAT-2026-001 --json

aga loop start --project-key mall-order --work-id FEAT-2026-001 --goal "实现并验证需求"
aga loop status <run-id>
aga graph create --project-key mall-order --manifest task-graph.json --json
aga graph claim release-070 implement-api --project-key mall-order --owner codex-session-01 --platform codex --json
aga graph review release-070 implement-api --project-key mall-order --review-id spec-001 --stage spec --decision approved --reviewer reviewer-01 --summary "规格符合" --json
aga spec create --project-key mall-order --manifest canonical-spec.json --json
aga spec preview order-lifecycle --project-key mall-order --delta change-001.json --json
aga spec bind order-lifecycle --project-key mall-order --work-id FEAT-2026-001 --delta change-001.json --json
aga spec trace order-lifecycle --project-key mall-order --json
aga dashboard
aga check --json

中央任务图（0.7 alpha）

aga graph 将 Initiative → Work Item → Task 的来源、验收映射和依赖关系保存在 AGA_HOME/projects/<project-key>/task-graphs。业务仓库不会生成任务图、状态、租约或结果文件。

只有 task 节点可被 claim。依赖未完成、执行器能力不足或已有活跃 lease 时失败关闭；过期 lease 可由其他执行器恢复。结果只接受 DONE、DONE_WITH_CONCERNS、BLOCKED 和 NEEDS_CONTEXT，并以 outcome_id 生成幂等回执。Codex、Claude Code、TRAE 使用 Tier 1 host adapter，其余平台安全降级为串行 CLI。capability 由 adapter 提供，不接受调用者任意自报。

并行不是由调用方声明开启：只有 Tier 1 adapter、互不依赖的 Task、不同的有效隔离 workspace，且 manifest 中非空 write_scope 没有父子路径重叠时，第二个 claim 才会成功。其他平台以及未声明写集、 共享 workspace 或写集相交的情况全部失败关闭并串行推进。

L1 的成功 outcome 直接完成；L2/L3 先进入 review_pending，必须按 spec（规格符合性）再 quality（代码质量）的顺序获得 approved。任一阶段要求修改会让任务回到可重新 claim 的阻塞态。 只有最终 completed 才会解锁依赖，因此串行与并行共享同一完成门禁。

workspace_requirement: isolated 的 Task 只有在 work_id 仍处于 build、已绑定 owner 一致、身份有效且 lease 存活的隔离 workspace 时才返回受限业务源码写权限；每次执行前还必须用 aga graph authorize 复检 workspace identity、record hash 和双 lease。提交、推送、远端发布、生产写入和权限提升始终禁止。

完整 manifest、命令和恢复语义见 中央任务图协议。

中央 Living Spec（0.8 alpha）

aga spec 把 canonical spec、delta、合并回执和版本 hash 保存在 AGA_HOME/projects/<project-key>/specs，不会向业务仓库复制 Spec 文件。Requirement 与 Scenario 使用稳定 ID； delta 支持 add、modify、remove、rename，其中 rename 只修改标题、不改变稳定 ID，remove 必须携带审批人与理由。

preview 只计算结果，apply 要求 base_revision 精确匹配。重复 delta ID 与相同内容返回幂等回执， 同 ID 不同内容、缺失目标、重复 ID、过期 revision 和未授权删除全部失败关闭。协议与完整 JSON 示例见 中央 Living Spec 协议。

工作项可用 aga spec bind 绑定一个经过 preview 的 delta；archive-complete 会在中央归档前应用该 delta， 并把 merge receipt 写入工作项事件。aga spec trace 聚合 Work Item phase、当前 verification evidence、 Task Graph 状态和匹配的 spec:<spec-id>#<requirement-id>/<scenario-id> acceptance ref。任务图创建时会拒绝悬空 Spec 引用。

验证证据协议

Feature 默认使用 test-first，Bug 强制使用 test-first。进入源码写入阶段前必须存在当前 epoch 的 red 或已审查例外；verify-pass 和归档前必须满足 green/regression。文档、配置 等不适合制造失败测试的 Feature 可在创建时显式使用 validation。

普通证据不能手工填写退出码和 hash，必须由 aga verification run 在当前授权 workspace 中 使用原生 executable + argv 执行并自动采集。命令前后会计算声明范围的源码/测试快照， verify-pass 和归档还会复检漂移；手工 record 只保留已审查 exception：

aga feature --project-key mall-order --risk-level L1 --verification-strategy validation --verification-reason "文档确定性校验" --verification-source docs FEAT-DOC-001 更新说明
aga verification run --project-key mall-order --work-id FEAT-DOC-001 --type green --executable node --arg scripts/check-docs.mjs --json

协议文件只位于中央 AGA_HOME。修改工作项声明的验收输入会开启新 epoch，使旧证据失效。 命令格式、hash 约束、L3 例外和当前捕获边界见 验证证据协议。

隔离工作区

WorkspaceProvider 统一描述三种执行位置：

• current：继续使用当前项目目录，保持串行兼容，但不具备并行隔离保证；
• host-native：识别 Codex 等宿主已经创建的 linked worktree；
• git-worktree：创建位于 AGA_HOME/workspaces 的中央隔离目标。

plan/status 始终只读；create/adopt/renew/release/cleanup 默认只预览，只有显式 --yes 才会重新检查 owner、lease、identity、Git 登记和 provenance 后执行。release 只解除中央绑定，不删除目录；cleanup 只处理 AGA 创建且未漂移的中央 worktree，dirty、未知来源和 host-native 一律拒绝。无任务提交的分支会随 worktree 删除，有提交的任务分支会保留。

项目可在中央配置最多 8 条有序 baseline 命令。工厂只接受原生 executable + argv，不执行 shell 字符串、不自动读取 package.json scripts，也不允许 Python、.cmd/.bat/.ps1/.sh 或 shebang 包装器。命令只在显式授权创建的中央 git-worktree 中运行；通过结果的命令、超时、exit code、时长和输出 hash 会进入工作项事件链，完整输出不会持久化。命令失败、超时或令 Git 工作区变脏时，本次 worktree/分支会回滚。baseline 参数不得携带密钥。包含 submodule gitlink 的仓库当前直接拒绝隔离创建，不会隐式拉取外部代码。

git-worktree 不向业务工作树生成工厂文件，但 Git 必须在原仓库 common directory 登记 worktree 和本地分支。具体字段和安全边界见 工作区生命周期。

Loop 与 Watch Worker

Loop 是持久化的闭环状态机，阶段为 intake → route → prepare → execute → verify → diagnose/repair → record。每个动作都有 action id、租约、证据和事件链；重复失败、修复次数、工具动作、迭代次数与总时长均有硬上限。Loop 不等于无限自循环，也不会自行越过发布、生产写入或人工审批边界。

Watch Worker 是可选的中央任务队列执行器，不代表平台兼容范围。当前后台执行器只支持本机已安装并登录的原生 Codex CLI；任务正文被视为不可信需求输入，通过 stdin 传入，不能覆盖工厂规则或授权边界。每个待执行任务必须提供 work_id，对应工作项必须处于 build、绑定有效隔离 workspace，启动时的 --owner 必须与 workspace lease owner 一致；否则 scan/run 只报告 blocked，不启动执行器。

aga watch ingest --project-key mall-order --json
aga watch ingest --project-key mall-order --no-vision --json
aga watch scan --project-key mall-order --owner codex-session-01 --json
aga watch start --project-key mall-order --owner codex-session-01
aga watch status --project-key mall-order --json
aga watch stop --project-key mall-order

默认每 300 秒扫描，连续 3 次无任务停止，单次最多处理 3 次任务尝试，同一任务最多尝试 2 次，单任务默认超时 45 分钟。

智能问题投递箱

项目中央目录 AGA_HOME/projects/<project-key>/tasks/dropbox 可以直接接收：

• .csv：按中英文常用列名逐行转换任务；
• .xlsx：安全读取 OOXML 首个工作表，不执行公式、宏和外部链接；
• .png、.jpg、.jpeg、.webp：通过本机 Codex CLI 的 --image 只读分析能力提取问题草稿；
• .json、.jsonl、.md：沿用原有任务格式。

旧二进制 .xls 不受支持，会进入 quarantine 并提示另存为 .xlsx 或 .csv。原文件按内容 SHA-256 去重；成功后保存在 archive，失败文件保存在 quarantine，解析回执保存在 receipts。截图默认进入 drafts 的 pending_confirmation，不会因为图片中出现命令或授权文字就直接执行。

CSV/XLSX 至少需要标题列，推荐列如下：

id | work_id | type | title | body | status | project_key
问题编号 | 工作项 | 类型 | 标题 | 问题描述 | 状态 | 项目

只有具备有效 work_id 且状态为 pending/open/new/待处理/新增 的表格记录会进入 inbox；其余记录进入 drafts。即使进入 inbox，仍必须通过工作项 build、隔离 workspace、owner/lease 与验证门禁。

aga watch start/run 会在每轮任务扫描前自动摄取 dropbox。aga watch scan 保持只读，不调用视觉模型，也不移动文件。需要只归档截图、暂不调用视觉模型时使用：

aga watch ingest --project-key mall-order --no-vision --max-files 100 --json

完整操作、表头映射、截图草稿确认和故障排查见 智能问题投递箱教程。

科学评估体系

科学评估用于 Skill、路由和工厂发行候选，不要求每个普通业务需求都重复跑评估。外部执行器负责收集重复样本，工厂只读取结构化证据，不执行评估文件中携带的命令。

aga eval task-set list --json
aga eval task-set show aga-core-v1 --json
aga eval task-set plan aga-core-v1 --json
aga eval run --manifest config/eval/manifest.example.json --samples config/eval/samples.example.json --task-set config/eval/task-sets/aga-core-v1.json
aga eval run --manifest ./bundle-manifest.json --samples ./bundle-samples.json --bundle ./my-bundle.aga-bundle.json
aga eval list --json
aga eval show <subject/evaluation/input-hash>
aga eval compare --baseline <ref> --candidate <ref>

内置 aga-core-v1 提供路由、平台生命周期、工作流、Loop 和 Bundle 五类共 20 个代表任务，每项至少规划 3 次独立运行。采样计划只包含任务身份、平台和确定性检查，不包含或执行 shell 命令。

传入 --task-set 后，每个样本必须携带 task_id 与正整数 run_index，确定性 check 集合必须与任务契约完全一致；缺少任务覆盖、重复 task/run 身份或 task-set hash 漂移时，评估保持 inconclusive 或直接失败，不能生成发布凭据。不传 --task-set 时仍兼容 0.8 的普通 Skill 评估样本。

报告包含：

• pass_rate；
• Pass@k = 1 - C(n-c,k) / C(n,k)，衡量 k 次中至少一次成功；
• Pass^k = pass_rate ** k，衡量连续 k 次都成功；
• Wilson 95% 区间；
• 加权 Rubric 与逐项阈值；
• included / flagged / excluded 数据质量；
• 耗时、Token、成本、工具动作和人工介入率。

确定性检查是发布硬门禁。只有 LLM 评分、缺少证据 hash、清洁样本不足或评估契约发生漂移时，结果只能是 exploratory 或 inconclusive，不能签发发布凭据。aga publish 默认只预览；--yes 也只记录本地外部发布授权，不执行 npm、Git 或远端发布。

Bundle 发行时可用 --bundle 将评估主体严格绑定到打包产物的 bundle_id、版本和内容 hash。随后 aga bundle distribute 会复检同一候选，默认只预览；只有同时提供 --yes --subject-hash <hash> 才安装，并在中央 AGA_HOME 写入绑定评估凭据、授权和安装回执 hash 的分发回执。

aga-any 的产品化候选使用中央状态机串起创建、状态/下一步、评估 Review、人工批准和分发预览：

aga skill candidate create team-review --bundle ./team-review.aga-bundle.json
aga skill candidate status team-review --json
aga skill candidate review team-review --evaluation <subject/evaluation/input-hash>
aga skill candidate approve team-review
aga skill candidate approve team-review --yes --subject-hash <sha256> --reason "reviewed"
aga skill candidate distribute team-review --platform codex
aga skill candidate distribute team-review --platform codex --yes --subject-hash <sha256>

Dashboard 的 Eval 区显示同一 subject/evaluation 最近 12 个结果，并明确标记契约漂移导致的不可比记录；平台区按“已验证、兼容分发、显式 CLI”展示 33 个平台的真实成熟度，不再把注册数量等同于同等自动化能力。

Dashboard

aga dashboard
aga dashboard --no-open --port 8765
aga dashboard --json

Dashboard 只监听 127.0.0.1，用一次性引导 Token 换取 HttpOnly Session Cookie，并校验 Host、Origin、产物白名单和 256 KiB 预览上限；响应同时限制浏览器权限并禁止缓存、嵌入和跨源资源读取。页面只读，包含中央任务图的就绪、执行中和待 Review 摘要；业务仓库只执行禁用 Hook 和可选锁的 Git 摘要查询。

操作队列把工作项、Task Graph、Loop、Eval 和 Skill Candidate 的阻塞或下一步聚合成最多 100 条命令，并优先呈现 workspace 漂移、人工等待和高风险阻塞。工作项详情同时展示隔离 workspace 健康度、必需审批完成度，以及 Loop 修复轮次、停止原因和待确认动作。Dashboard 只能复制命令到终端，不执行命令、不持有写权限；所有实际变更仍由用户在终端触发 CLI，并经过原有确认与领域门禁。

界面支持跳到主要内容、键盘 Tab 导航、可读进度语义、清晰焦点样式和减少动画偏好；平板与手机宽度不会隐藏操作队列、运行状态或诊断信息。

当前不提供 MCP：Codex 与 TRAE 尚未出现 CLI JSON、用户级 Skill 和 Dashboard 无法解决的共同协议缺口，Claude Code 也没有可用客户端可形成真实证据。重新评估条件见 只读协议适配决策。

从旧版迁移

先检查，再导入旧中央证据：

aga migrate inspect --legacy-root D:\old-ai-factory --json
aga migrate import --legacy-root D:\old-ai-factory --dry-run --json
aga migrate import --legacy-root D:\old-ai-factory --json

导入会在 AGA_HOME/migrations 创建内容寻址的不可变快照，并登记仍存在的源码项目；不会把旧工作项重新写进业务仓库。

旧版曾写入业务项目的薄入口可以显式清理。默认只预览：

aga cleanup project --project-root D:\projects\mall-order --json
aga cleanup project --project-root D:\projects\mall-order --yes --json

清理器只处理 AI-FACTORY-PROJECT 生成区和带 AI-FACTORY-MANAGED-SKILL 标记的文件；无标记的同名 Skill 与生成区外的手写内容不会删除。

平台能力边界

aga platform list --json
aga platform detect --json
aga platform doctor --platform codex --json
aga doctor --platform codex --workspace . --json

平台路由分三类：

• user_auto：已验证用户级 Skill/Rule 安装与发现契约，真实自然语言选择仍由平台管理；
• user_command：可安装用户入口，但自动触发强度取决于平台；
• explicit_cli：平台没有安全的用户级入口，使用全局 aga 命令。

“支持 33 个平台”表示注册、分发和能力降级契约完整，不表示 33 个平台都拥有相同 Hook 或相同深度的自动路由保证。

开发与门禁

npm test
npm run pack:check

check:source 会拒绝：

• Python 源码、字节码或缓存；
• 旧仓库复制式安装器、包装命令和项目内中央状态；
• npm 安装生命周期脚本；
• CI 或活动文档中的 Python 执行命令；
• 非法 JSON、Node 语法错误或平台注册表漂移。

Node 测试覆盖中央零写入、平台生命周期、持久 Loop、科学评估、发布凭据、Dashboard 会话安全、迁移清理与有界 Worker。

安全边界

• 任务、评估样本和业务仓库内容均按不可信输入处理。
• 中央 JSON 拒绝重复 key；重要状态使用原子写、锁、hash 与追加事件链。
• 目录链接、文件链接、硬链接、路径穿越和超限文件默认失败关闭。
• 自动流程不得自行提交、推送、发布、修改生产数据或降低测试标准。
• 真实业务代码修改仍发生在用户授权的业务工作区；“零写入”特指不生成工厂规则、Skill、工作项和运行状态。