AI 编程流水线边界升级

本仓库用于实验和沉淀「AI 编程流水线 / Orchestrator + Subagent + Shim」相关实践，当前主要聚焦：

• 使用 gxd-subagent-shim 将 Codex / Claude 等代码模型接入本地工程；
• 通过 .artifacts/agent_runs/ 记录可追溯的执行审计日志；
• 在「自动化程度」与「安全边界」之间寻找折中方案。

---

当前版本与 Guardrails 里程碑

• Shim 版本：gxd-subagent-shim 0.2.3（源码位于 gxd-subagent-shim-0.2.3/ 目录，推荐以 editable 方式安装）。
• Policy 版本：POLICY_VERSION = "0.3.0"（Step JSON 模板和 Output Contract 的基线版本）。
• 默认后端：claude（可通过 --backend=codex 或 SUBAGENT_BACKEND=codex 切换为 Codex）。
• 本轮 Guardrails 升级已经在 shim 内部落地：
  • Scope Guard（变更面与 allowed_paths / forbidden_paths 自动比对）；
  • Output Contract 8 段式输出完整性校验；
  • Step JSON 的 JSON Schema 校验；
  • --prompt-file 文件输入通道，避免跨 shell 的 JSON 引号问题；
  • 通过 --validate-schema/--validate-scope/--validate-contract 与 SUBAGENT_VALIDATE_* 环境变量控制各类校验；
  • 在 .artifacts/agent_runs/<RUN_ID>/ 下统一归档 meta、events 以及各类校验结果。

详细验收过程见：docs/06-验收文档/0.2.3-guardrails-升级与验收.md。

---

文档导航 (Documentation)

文档	说明
AGENTS.md	核心规范 —— Orchestrator 角色与流水线约定（含严格模式说明）
docs/00-快速开始/index.md	文档索引 —— 完整文档目录导航

快速链接

• 使用指南：如何安装与使用 gxd-subagent-shim
• 进阶配置：环境变量、运行记录与故障排查
• 集成指南：在新项目中接入 Orchestrator + Shim
• 设计分析：Agent 提示词一体化设计分析
• Git 集成：Agent 与 Git 集成流程
• Shim 技术参考：gxd-subagent-shim 项目说明
• 提示词演化：提示词与流程的演进记录
• 问题文档：已知问题与工程分析
• 验收文档：各版本问题修复与 Guardrails 升级的验收记录

---

仓库结构

011.AI编程流水线边界升级/
├── AGENTS.md                      # Orchestrator 核心规范（本仓库专用）
├── docs/                          # 文档目录（按主题分组，主要为中文）
│   ├── 00-快速开始/
│   │   ├── index.md               # 文档索引
│   │   ├── getting-started.md     # 使用指南
│   │   └── command-generator.md   # 命令生成提示词
│   ├── 01-使用指南/
│   │   ├── configuration.md       # 进阶配置（环境变量、日志、审计）
│   │   └── integration.md         # 与项目集成指南
│   ├── 02-设计文档/
│   │   ├── design-analysis.md     # 设计分析
│   │   └── git-integration.md     # Git 集成方案
│   ├── 03-技术参考/
│   │   └── shim-reference.md      # Shim 项目说明与接口细节
│   ├── 04-演化历史/
│   │   ├── prompt-evolution.md    # 提示词演化
│   │   └── lecture-notes.md       # 讲义/课程笔记
│   ├── 05-问题文档/               # 问题与工程分析
│   └── 06-验收文档/               # 版本验收与问题修复记录
├── gxd-subagent-shim-0.2.2/       # shim 源码（当前版本 0.2.3）
└── .artifacts/                    # 运行审计目录（已在 .gitignore 中忽略）

---

开发者指南

1. 安装 shim（可选但推荐）

在仓库根目录执行：

cd gxd-subagent-shim-0.2.3
python -m pip install -e .

这会以 editable 方式安装 gxd-subagent-shim，方便在本地修改源码并立刻生效。

2. 在新项目中初始化策略文件（v0.2.3+）

gxd-subagent-shim 0.2.3 新增了 init 子命令，可以快速在新项目中初始化 Orchestrator 策略文件：

# 方式1：进入目标项目目录后执行
cd /path/to/your-project
gxd-subagent-shim init

# 方式2：使用 --target 指定目标目录（无需切换目录）
gxd-subagent-shim init --target /path/to/your-project

# 如果目标目录已有 AGENTS.md 或 agents/ 目录，使用 --force 强制覆盖
gxd-subagent-shim init --force

# 查看帮助
gxd-subagent-shim init --help

执行后会在目标目录创建：

• AGENTS.md — Orchestrator 策略入口文件
• agents/ — 策略模块目录（包含 contracts、playbooks、policy、templates 等）

这样新项目就可以立即使用 Subagent Orchestrator 的完整策略框架，无需手动复制文件。

3. 推荐：使用 prompt 文件 + --prompt-file 调用（Guardrails 模式）

严格模式下，推荐通过 文件 传入 Step JSON，并在 CLI 上开启 Guardrails：

# 将 Step JSON 写入 step.json，内容可参考 AGENTS.md 中的 Step JSON 模板
@'
{
  "task_kind": "step",
  "task_id": "hello_world",
  "run_id": "hello_world_20260106T000000Z_local",
  "step_id": "S1",
  "step_title": "Hello World via prompt-file",
  "step_description": "Return a short greeting.",
  "acceptance_criteria": [
    "Subagent returns a short greeting",
    "Output Contract includes all 8 sections",
    "No shim-level validation errors"
  ],
  "scope_guard": {
    "allowed_paths": ["docs/**"],
    "forbidden_paths": ["AGENTS.md", ".artifacts/**"]
  },
  "policy_version": "0.3.0"
}
'@ | Set-Content -Encoding utf8 step.json

# 通过 --prompt-file 调用 shim，并启用三类 Guardrails 校验
gxd-subagent-shim create `
  --prompt-file step.json `
  --backend=claude `
  --validate-schema `
  --validate-scope `
  --validate-contract

运行后可在 .artifacts/agent_runs/<RUN_ID>/ 下查看：

• meta.json：包含 shim_version / policy_version 等 run 元信息；
• events.jsonl：运行事件与 Guardrails 校验事件；
• steps/<STEP_ID>/rounds/R0/：原始 prompt、后端输出、校验结果等。

4. 快速示例：直接通过参数传 JSON Prompt（不推荐用于复杂场景）

在某些快速试验场景，可以直接将 JSON 字符串作为位置参数传入：

$prompt = '{"task_id": "hello_world", "step_id": "S1", "instruction": "输出一段问候语"}'
gxd-subagent-shim create $prompt --backend=claude

这种写法在不同 shell / CI 环境中容易因为引号和转义规则差异导致 JSON 被拆坏，推荐仅在本地最小化试验时使用；在真正的 Orchestrator 流程中，应优先采用第 2 节的 --prompt-file 方案。

---

Git 与忽略规则

本仓库已提供基础的 .gitignore，主要忽略：

• .artifacts/agent_runs/ 等运行审计产物；
• subagent.log 等本地日志；
• .DS_Store、__pycache__/、*.pyc、虚拟环境目录、打包产物等。

如在本地新增 IDE 配置、临时脚本或大数据量目录，建议一并追加到 .gitignore 中，避免误提交。