autonomous-common

Autonomous Common Infrastructure

autonomous-dev、autonomous-review 和 autonomous-dispatcher 共用的工作流强制执行钩子和可由 Agent 调用的实用脚本。其他 autonomous-* 技能会引用这里的脚本和钩子——这些引用路径出问题时，通常应该检查这个技能。

如需了解可选的开发/评审经验记录、限定范围的事实修订、本地环境参考资料或合并后的文档回写，请阅读 references/session-knowledge.md。评估结果 可能会显示无需更新；只有有用的文档差异才会创建提交/PR。

npx skills add 用户的设置

运行 npx skills add 后，请在项目根目录下为你的编码 Agent 运行一次安装程序：

Agent	安装程序	写入位置
Claude Code	bash .claude/skills/autonomous-common/scripts/install-claude-hooks.sh	.claude/settings.json
Qoder	bash .claude/skills/autonomous-common/scripts/install-qoder-hooks.sh	.qoder/settings.json
Antigravity	bash .claude/skills/autonomous-common/scripts/install-antigravity-hooks.sh	.antigravity/hooks.json
Cursor	bash .claude/skills/autonomous-common/scripts/install-cursor-hooks.sh	.cursor/hooks.json
Kiro CLI	bash .claude/skills/autonomous-common/scripts/install-kiro-hooks.sh [--agent <name>]	.kiro/agents/<name>.json（默认值：default）
Gemini CLI	bash .claude/skills/autonomous-common/scripts/install-gemini-hooks.sh	.gemini/settings.json
Codex CLI	bash .claude/skills/autonomous-common/scripts/install-codex-hooks.sh（Python 3.11+）	.codex/hooks.json + .codex/config.toml
Windsurf	bash .claude/skills/autonomous-common/scripts/install-windsurf-hooks.sh	.windsurf/hooks.json
Kimi CLI	bash .claude/skills/autonomous-common/scripts/install-kimi-hooks.sh [--project]	~/.kimi/config.toml（默认；--project 写入 .kimi/config.toml）

每个安装程序都会在项目范围内配置工作流钩子，因此它们会在仓库中的每条 shell 命令执行时触发——而不只是在明确加载 autonomous-* 技能时触发。如果不进行此设置，技能 frontmatter 中声明的钩子命令只会在对话中某个技能处于激活状态时运行；这正是导致 #68 被关闭的问题回归。

有关各 Agent 的架构映射参考，请参阅 docs/cross-agent-hooks.md。

项目侧的 scripts/ 和 hooks/ 符号链接

上述 IDE 安装程序只会写入 IDE 配置文件（例如 .claude/settings.json）。项目侧的 <project>/scripts/ 符号链接（让 dispatcher-tick.sh 能找到 autonomous-dev.sh、lib-agent.sh 等文件）以及 <project>/hooks 目录符号链接，则由一个独立于 IDE 的引导脚本管理——这是适用于 scripts/ 中已有项目本地文件的项目的规范模式：

# From your project root, after `npx skills add`:
bash .agents/skills/autonomous-common/scripts/install-project-hooks.sh

该脚本的功能：

• 将已安装的 autonomous-dispatcher/scripts/ 中的每个 *.sh 符号链接到 <project>/scripts/，不会覆盖 autonomous.conf 或项目专用部署辅助脚本等真实（非符号链接）项目本地文件。
• 如果上游移除了文件，则清理失效的符号链接。
• 将 <project>/hooks 符号链接到 autonomous-common/hooks（如果已存在真实目录，则拒绝覆盖）。
• 安装每个工作树的 git pre-push 钩子（#65）。使用 --no-git-hook 可跳过。

此操作是幂等的——每次运行 npx skills update 后都应重新运行，以便自动获取新增的上游文件（例如该技能集新增 lib-*.sh 文件时）。这解决了 #153 背后的静默漂移问题：通过对单个文件执行 ln -s 而采用照搬清单方式进行引导的项目会漏掉新文件，导致 autonomous-review.sh 在任何评审工作开始前，就因对缺失文件执行 source 而退出。

旧版目录级回退方案（已弃用）

早期文档建议将项目的 scripts/ 目录替换为一个符号链接：

ln -sf .claude/skills/autonomous-dispatcher/scripts scripts   # DEPRECATED

这样会丢失 scripts/ 中任何项目本地文件。请改用 install-project-hooks.sh——它能正确处理已有项目本地内容的目录，重新运行时也会获取上游更改。

必需的 Claude Code 插件

仅适用于 Claude Code。安装程序会提示安装这些插件；如果手动安装，请在 .claude/settings.json 的 enabledPlugins 下添加：

{
  "enabledPlugins": {
    "code-simplifier@claude-plugins-official": true,
    "pr-review-toolkit@claude-plugins-official": true
  }
}

不支持钩子的 IDE（Cursor、Windsurf）会跳过安装程序和符号链接——技能无需钩子也能使用，但必须手动遵循工作流步骤。

此处包含的内容

• hooks/ — 工作流强制执行钩子（block-push-to-main、block-commit-outside-worktree、check-pr-review、check-shellcheck、verify-completion，……）。规范列表和各钩子的语义请参阅 hooks/README.md。
• scripts/ — 开发／审查技能使用的、可由 Agent 调用的实用工具：
  • session-knowledge.sh / session-knowledge.py — 私有共享任务记录、可选的已验证候选项、本地知识，以及隔离的文档提交（使用 Python 标准库）
  • install-project-hooks.sh — 与 IDE 无关的项目端引导脚本：将调度器 *.sh 符号链接到 <project>/scripts/（不会覆盖项目本地文件），将 <project>/hooks 符号链接过去，清理失效链接，并安装 git pre-push 钩子。每次运行 npx skills update 后都要重新运行（修复 #153）
  • lib-installer.sh — 所有各 Agent 安装程序共用的合并／写入辅助函数
  • lib-installer-translate.sh — 为近似克隆的 Agent 提供架构转换辅助函数（事件名称映射、工具名称映射、超时单位转换）
  • install-claude-hooks.sh — Claude Code 安装程序（写入 .claude/settings.json）
  • install-qoder-hooks.sh — Qoder 安装程序（写入 .qoder/settings.json——与 Claude Code 使用相同的架构）
  • install-antigravity-hooks.sh — Antigravity 安装程序（写入 .antigravity/hooks.json——仅包含钩子的文件；其约定来自社区观察，Google 未提供文档）
  • install-cursor-hooks.sh — Cursor 安装程序（写入 .cursor/hooks.json——使用 version: 1 封装、camelCase 事件和 Shell 匹配器）
  • install-kiro-hooks.sh — Kiro CLI / Amazon Q 安装程序（写入 .kiro/agents/<name>.json——包含 camelCase 事件、execute_bash/fs_write 匹配器，以及以毫秒为单位的 timeout_ms 的 Agent 定义）
  • install-gemini-hooks.sh — Gemini CLI 安装程序（写入 .gemini/settings.json——使用 BeforeTool/AfterTool 事件，以及 run_shell_command/write_file/replace 匹配器）
  • install-codex-hooks.sh — Codex CLI 安装程序（需要 Python 3.11+ 的 tomllib，生成可解析工作树根目录的 .codex/hooks.json，设置规范的 [features] hooks = true，并安全迁移已弃用的 codex_hooks 别名）
  • install-windsurf-hooks.sh — Windsurf 安装程序（写入 .windsurf/hooks.json——使用会折叠匹配器信息的 snake_case 事件；没有按工具区分的匹配器字段）
  • install-kimi-hooks.sh — Kimi CLI 安装程序（默认写入用户级配置 ~/.kimi/config.toml，或使用 --project 写入 .kimi/config.toml；生成 TOML [[hooks]] 块）
  • claude-settings.template.json — 所有各 Agent 安装程序应用的规范钩子列表
  • gh-as-user.sh — 以真实用户身份运行 gh（重新触发机器人审查时需要，例如 /q review）
  • mark-issue-checkbox.sh — 从 Agent 切换 GitHub issue 正文中的复选框状态
  • reply-to-comments.sh — 回复 PR 审查评论
  • resolve-threads.sh — 批量解决 PR 上的审查讨论串

钩子和脚本的详细说明请参阅各自的 README／源文件。此 SKILL.md 仅列出可用内容，方便你找到要编辑的正确文件。