@event4u/agent Config

Agent Config — 每项声明均经过机器验证，包括这些徽章中的制品数量

_{这些数量的统计方式 — 使用唯一的规范计数器 agent-config → update_counts --check，从目录树重新统计全部六项；任一项相差 1 都会导致 CI 失败。有两个统计口径与链接目录所显示的内容不同，因此在此明确说明，而非留待读者自行推断：Commands 211 递归统计所有命令文件（链接目录的顶层有 62 个）；Rules 122 统计源规则，而链接目录中的投影有 121 个——其中一条规则处于休眠状态，未被投影。Personas 29 不包括目录 README。统计对象是文件和目录：这些数量都不代表质量、启用情况或采用程度。}

30 秒上手 — 只需一个只读子 Agent，即可在任意仓库中检查“完成”状态，无需安装其他内容：快速切入点 ↓。从证据开始，而非从目录开始：event4u-app.github.io/agent-config/proof/。

本 README 中的每项公开声明都经过机器验证——自行验证。 在一个充斥着无依据醒目数字的市场中，这套机制会将每项声明与可解析的证据绑定，否则自身构建就会失败。

查看变更影响范围

agent-config code-graph map 会在 agents/map/ 中绘制离线地图：代码、数据、系统、接口、运行时、交付、历史和领域。事实会保留 file:line，采取行动前请重新读取。选中一个文件：所有涉及的区域都会亮起。

更多视图

选择你的使用方式——开发者 · 创始人 · 内容 · 代理机构 · 财务 · 运营。添加套件。获得精简的命令集，而不是 500 件工件的大杂烩。自行选择 AI 提供商。

丰富的技能、命令和受治理规则库——再加上一个根据意图加载合适技能的能力路由器，以及带有共识审查的多 Agent 编排。整个层编译为 20 种宿主 Agent——检测到 23 种，其中 3 种仅用于导出（Claude Code、Cursor、Augment、Cline、Windsurf、Copilot、Gemini CLI、Codex、Continue、Zed、JetBrains、Aider 等）。常驻进程仅在遵循监督政策的情况下才被允许；本仓库于 2026-08-27 采纳了该政策——这是一条规则，并非对任何当前运行内容的描述。其上还有六种按角色设计的入口路径，因此任何宿主都能成为可靠的团队成员——不必绑定单一模型或供应商。

30 秒上手

# 1. Install — on a terminal with a display, the browser wizard launches
#    automatically; the same TypeScript installer runs the real install behind it.
npx -y @event4u/agent-config init

# 2. Pick your profile + tools in the wizard, click Finish.
#    (Writes ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …)

# 3. First real task — agent refines, plans, verifies.
/work "your first real task"

或者先在自己的仓库中试用一个子 Agent：

mkdir -p .claude/agents
curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
  -o .claude/agents/production-validator.md
# then in Claude Code:  @production-validator check this branch is actually done

production-validator 为只读工具：它会搜寻已发布路径上的模拟对象和存根，并要求提供真实系统的证据（功能说明）。 完整套件只需一条命令——快速入门 ↓。

---

有何不同

既深入，又严谨，并且坦诚说明自身刻意不做什么：

• 深度由路由器自行调度——能力路由器根据意图加载合适的技能，而非倾倒 500 件工件构成的上下文。
• 在每种宿主上实施治理——规则会编译为每种工具的原生格式；在支持钩子的宿主上，还会添加确定性运行时钩子。这种与配置空间相关、与宿主无关的治理能力就是护城河（治理优势 · 各宿主的执行情况）。
• 精准卸载——仅处理共享配置中的自有键，绝不触碰其他配置项；使用 --purge 时，只删除自身记录的文件，绝不删除锚点。
• 按套件限定安装范围——写入当前启用的套件及其依赖；其他套件只需可触达。

刻意不做的事——核心是治理层，并可选择启用独立的内嵌引擎（代码智能、受控触达、设置图形界面、基准实验室——内嵌引擎原则）：**没有强制或始终运行的守护进程，没有独立状态数据库，没有自我改写的记忆，也没有自动构建流水线。**引擎从不强制启用；未经实测证明能带来提升，默认也不会启用；并且会随调用它的命令一同终止。宿主 Agent 负责运行循环；所有学到的变更都由人工审查；同一层可在不同工具间保持可移植。拥有能力，无需操心后台进程。

**项目来源（如实说明）。**技能、规则和角色设定提炼自 TypeScript 和 PHP 代码库的真实生产实践。治理机制与技术栈无关，但领域启发式在孕育它们的技术栈中最为成熟——对于其他技术栈，请将现有覆盖视为前景良好，而非已经验证；也请告诉我们不足之处。

查看各宿主的实际支持情况，或直接前往一分钟内即可完成的操作。

选择你的档案——六种入门路径

agent-config setup 会将 profile.id 写入 .agent-settings.yml，并带你进入该档案的首个页面。每个体验页面都包含完整详情——适用人群、首批命令和技能、工具包与流程，以及刻意不加载的内容。

档案	适用人群	体验页面
👩‍💻 developer	IC 工程师	页面
✍️ content_creator	作者、代笔者、营销人员	页面
🚀 founder	独立创业者／初创企业创始人	页面
🏛 agency	多客户交付团队	页面
💼 finance	CFO／兼职财务人员／FP&A	页面
🛡 ops	RevOps、支持、SRE 相关岗位	页面

不确定该选哪个？ 向导会询问一个包含 8 个选项的职位问题，并映射到最接近的档案。权威来源 src/agent-src/profiles/ · 架构 docs/contracts/profile-system.md · 软件领域之外 user-types/（园林绿化 · 金属加工 · 卡车——参见软件领域之外）。

工作流，而非原始命令

你不必记住命令——只需执行工作旅程。四种流程贯穿开发者的完整工作过程：

流程	从这里开始	工作旅程
🔍 探索	/feature:plan · /research	探索 → 规划 → 估算 → 优化，在开始构建之前完成
🔨 实现	/work · /implement-ticket	规划 → 实现 → 验证 → 提交
🔎 审查	/review-changes · /judge	自我审查 → 评判 → 质量修复 → 威胁建模
🚢 交付	/commit · /pr:create	分批提交 → 创建 PR → 回复审查意见

各流程组合使用的技能及规范路径：docs/flows.md。

更新日志 · 升级到 14.x · 重大变更 · 最新版本 · 讨论区

_{分发方式：npm install @event4u/agent-config。主版本升级遵循 semver；每个版本都会包含一条 ### Breaking 条目——所有主版本均收录于 BREAKING_CHANGES.md。}

---

创意工具包——电影级 AI 视频。 从脚本 → 角色一致性图像 → 动态+音频提示词 → 服务商渲染 → 拼接片段，并默认设置 AIV_DRYRUN=true 以控制成本。这是内容／创作者体验中的一项核心能力——不再是该软件包的主打功能。参见 /video:from-script。

法律工具包——不构成法律建议。 欧盟／德国法律工具包（合同／NDA／DPA 审查、分诊）仅用于辅助研究和起草——不提供法律建议，不能替代合格律师，也不得用于任何具体事项。它提供一般信息和通用模板，绝不审查个案。使用前请阅读 LEGAL_NOTICE.md。

完整目录——所有技能、规则、命令和指南：docs/catalog.md。重点是体验（档案 + 工具包），以及其背后的丰富功能。

在你的项目中使用

在使用方代码仓库中运行——通过 npx 引导安装，Agent 会识别你的技术栈，你可以端到端交付工作。首次安装？从快速入门开始。已经安装？支持的工具列出了已接入的 AI；docs/featured-commands.md列出了端到端工作流（/implement-ticket、/work、/commit、/pr:create）。深入了解：2 分钟演示。

安装范围。 每台机器选择一种范围——项目级（默认，推荐用于应用代码仓库）或用户全局级（推荐用于工具代码仓库 / dotfiles）。安装程序会通过 scope_guard 预检拒绝安装相互冲突的第二种范围。详情：docs/contracts/install-scopes.md。需要时清理：bash src/scripts/cleanup_other_scope.sh --confirm。

验证它

不要轻信这些说法——请验证。 docs/proof.md由源代码生成：其中包含一张说法→证据表（每项公开说法都关联到可解析的指针，否则 CI 会失败）、如实呈现的空值基准测试*，包括软件包未产生任何变化的运行结果*，以及一段“亲自验证”内容，可在全新检出中运行。如果它与源内容不一致，CI 就会失败——可复现性就是证据。请在 event4u-app.github.io/agent-config/proof/阅读，比较框架见 docs/us-vs-the-category.md。 最新测量结果：在一次修复后的会话中，建议性上下文注入将语言镜像违规次数从 555 降至 19，而两个阻断式防护分别从 8 降至 0、从 1 降至 0——建议性防护大幅减少了违规，只有阻断式防护将其彻底消除。这只是一次会话和事后解读，因此它是记录下来的先验判断，而非定律。

你是否在维护自己的技能目录？这里用于阻止查找替换式换皮 PR 的反换皮门禁也可以用于你的目录——docs/anti-reskin-gate.md。

遵循审计纪律——决策键存放在 agents/runtime/state/；回放日志为可选功能（hooks.runtime_journal.enabled）。 核心原则列出了四项不变量。

贡献

正在开发软件包本身？开发介绍 task ci 流水线，要求介绍工具链，维护者遥测（可选，默认关闭）介绍可选的测量流程。唯一可信的源代码目录是 src/（src/skills、src/rules、src/agent-src/）；切勿手动编辑 .augment/ 或 dist/agent-src/。

安全。 漏洞披露政策：SECURITY.md。威胁模型：docs/threat-model.md。

---

快速开始

一条命令。由检测驱动——自动发现并预选已安装的 AI 工具。点击“完成”之前不会写入任何内容。无需手动编写 YAML。

这四项是结构性的——它们是代码路径的属性，而非取决于你的机器。 所需的时间则不是：它主要受网络和注册表延迟影响。 CI 会在每次 umbrella 运行中测量安装到 doctor 的墙钟时间， 并连同测量条件一起发布，作为证据，而非承诺。

这条命令见上方 ↑。

无头模式 / CI： 在 CI、非 TTY、无头主机或使用任何 CLI 模式标志时，init 会跳过 GUI，改为运行非交互式安装程序。GUI 和 CLI 共用同一个安装程序（src/scripts/install.ts），因此两者产生的结果完全相同。标志、完整的退出选项集以及 --dry-run：docs/wizard.md · gui-wizard § 何时跳过 GUI。

选择特定 AI： --tools=claude-code,cursor,augment,…（任意子集）。--gui 会强制在通过 TTY 和无头模式检查后启动绑定到 loopback 地址、受 CSRF 保护的选择器；它不会覆盖 CI、AGENT_CONFIG_NO_UI 或 CLI 模式标志；与其中任何一项同时使用时会以非零状态码退出，而不会悄悄运行 CLI 安装。

验证钩子覆盖情况： npx @event4u/agent-config hooks:status（CI 使用 --strict，工具集成使用 --format json）。

范围（v2.5+）： init 只写入全局配置——~/.event4u/agent-config/、~/.claude/、~/.cursor/ 等。项目目录树中只会有 agents/overrides/。--project 仅供维护者使用，须通过 AGENT_CONFIG_DEV_MODE=1 启用（ADR-020、开发模式）。

从 v1.x 迁移？运行 npx @event4u/agent-config migrate — docs/migration/v1-to-v2.md。

---

agent-config 是什么——又不是什么

一个内容层——包含技能、规则、命令、指南和角色设定，通过 npm 分发，并映射为每种受支持 AI 工具的原生配置格式。技能使用 SKILL.md，其中包含特定于软件包的 frontmatter 键。

它不是 Agent 运行时。Agent 循环、大模型分发器和工具编排仍由宿主工具负责（Claude Code、Augment、Cursor、Cline、Windsurf、Gemini CLI、Copilot）。可以把它看作这些工具的操作手册和风格指南，而非替代品。

范围内	范围外
技能、规则、命令、指南、角色设定	Agent 循环 / 大模型分发器
多工具映射 + 精简流水线	软件包内部的执行引擎
记忆辅助工具（memory-add、memory-promote）	跨工具可观测性仪表板
Linter、CI、依据 JSON-Schema 进行 frontmatter 验证（契约）	运行时 GUI / Web 仪表板（只读的宿主状态栏不属于此类）
通过引用 + 确定性辅助工具编排技能	观点鲜明的自动技能解析器（替你做决定的 ML / 相关性排序）
由用户在映射时按配置文件 + 工具包筛选（ADR-040）	运行时解析器 / 守护进程（会话中途切换——有条件，计划在 6.0.0 之后）

要求你的 Agent 做什么

默认行为	使用 agent-config 后
盲目猜测并编辑	修改前先分析代码
偏离项目约定	遵循检测到的技术栈约定
跳过测试或凭空编造测试	使用项目的框架编写测试
使用通用的提交消息	遵循 Conventional Commits，并包含作用域 + 工单链接
跳过质量检查	运行项目的质量流水线并修复报告的错误
不附带上下文地创建 PR	根据 Jira / Linear / GitHub 信息编写结构化 PR 描述
没有证据就声称“已完成”	先通过实际执行验证，再声称完成

2 分钟演示 — /implement-ticket

旗舰命令。通过固定的线性流程端到端处理工单——遇到歧义时会暂停，而不是猜测。

/implement-ticket PROJ-123

Agent 按以下顺序执行：

refine → memory → analyze → plan → implement → test → verify → report

• 细化工单：如果验收标准含糊不清。
• 查询记忆：检索过去的决策、不变量和事件。
• 制定计划：任何文件被触碰之前，都由你确认。
• 实施：遵循 minimal-safe-diff + scope-control——不顺手修改无关内容。
• 测试（先运行针对性测试；成功后再运行完整测试套件）。
• 审查差异，交由七位评审者检查（错误、安全、测试、质量、架构、规范、过度构建）。
• 报告变更、评审结论和后续事项——然后停止。/commit 和 /pr:create 只是建议，绝不会自动运行。

任何歧义都会让流程暂停，并提供编号选项——绝不默默猜测。角色配置来自 .agent-settings.yml（roles.active_role）：senior-engineer（默认）、qa 或 advisory（仅制定计划）。

→ 命令参考 · 流程约定

同类命令 — /work（自由形式提示词）

使用相同的引擎，无需工单：

/work add a CSV export endpoint to the audit-log controller

第一轮会从五个维度为提示词评分，并根据评分档位进行路由：

档位	分数	操作
high	≥ 0.8	不打断，直接继续——在报告中列出验收标准和假设
medium	0.5–0.79	暂停并报告假设；请确认或编辑
low	< 0.5	暂停，并针对最薄弱的维度提出一个澄清问题

通过档位检查后，流程与 /implement-ticket 完全相同。自由形式目标 → /work；工单内容 → /implement-ticket。

→ 命令参考 · refine-prompt 技能

运行结束后： agent-config explain last 可还原执行轨迹（路由 · 记忆 · 评审团 · 暂停 · 提供方）——只读、已清除个人身份信息（PII）、可离线运行。文档

产品 UI 工作轨道

UI 类工作会路由到三组指令之一——ui（完整审计→设计→应用→审查→润色→报告）、ui-trivial（≤ 1 个文件、≤ 5 行：应用→测试→报告）、mixed（后端 + UI：约定→UI→集成）。现有 UI 审计是硬性关卡（ui-audit-gate）；润色最多 2 轮，优先处理无障碍问题。技术栈检测结果 → blade-livewire-flux / react-shadcn / vue / plain。

→ 思维模型（1 页）· 流程约定

---

自定义

配置档案 — 加载多少治理规则

安全底线（默认不执行破坏性操作 · 遇到不确定时先询问 · 使用与用户相同的语言）包含在每个配置档案中，作为安全护栏，而非安全边界。配置档案会添加指导规则。

配置档案	包含内容	适用场景
minimal	仅包含不可妥协的安全底线。成本最低、速度最快。	快速提问 · 临时脚本 · CI · Token 预算紧张
balanced（默认）	安全底线 + 日常指导（合理的默认值、审查提醒、常见陷阱）。	日常工作
full	包含所有内容，包括通常只有维护者才需要的低频规则。	开发 agent-config 本身 · 审计 · 高保真演示

底层加载范围：仅内核 · 内核 + 第 1 层 · 内核 + 第 1 层 + 第 2 层。详情：rule-router · kernel-membership · 配置 →。

**稳定性：**完整矩阵见 STABILITY.md。工作引擎（/work + /implement-ticket）：测试版。运行时调度器：稳定。工具适配器：实验性（仅限 full 配置档案）。

.agent-user.md 和 Ghostwriter — 语音原语

原语	语音	披露
personas/*.md	审阅视角（内部评议）	不适用
.agent-user.md（项目根目录，已加入 gitignore）	维护者自己的语音 — /post-as:me	无（你就是作者）
agents/reference/ghostwriter/<slug>.md（已加入 gitignore）	有记录的公众人物 — /post-as:ghostwriter	强制，不可移除

通过交互方式创建用户文件：/agents user init（架构）。Ghostwriter 集群：/ghostwriter:fetch <url-or-name> 会运行认证门禁；拒绝私人个体；架构层面禁止使用付费墙内容、泄露内容和私信内容。

在 Cloudflare 上自托管 MCP — 无需本地安装

可通过你自己的 Cloudflare Worker 将技能、命令、规则和指南作为 MCP 端点提供，任何 MCP 客户端都可通过 HTTP 访问。支持两种身份验证模式：public（默认）和 bearer-auth（操作员选择启用，MCP-Token Wrangler 密钥）。

task mcp:cloud:login         # one-time, opens browser
task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private deploys)

→ 操作员指南：mcp-cloud-setup · 各客户端配置：mcp-client-config · 端点：mcp-cloud-endpoints。

范围 — Lite，而非 Full。 Worker 通过 MCP 提示词和资源提供只读治理内容（技能 · 命令 · 规则 · 指南 · 上下文），以及少量只读工具（memory_lookup、chat_history_read、list_*）。它不会执行仓库的本地脚本（代码检查器、审计、task ci、工作引擎钩子）——这些功能需要按照快速入门进行本地安装。

内置的本地 stdio 服务已列入 Glama MCP Registry——它需要本地检出代码，而非开箱即用的安装（ADR-067）。

部署方式

形态	状态	路径
单用户工作区	✅ 当前支持	npx @event4u/agent-config init — 单台机器、单个用户；不支持远程同步
小型团队（3–10 人）	✅ 当前支持	共享的 agents/overrides/ Git 仓库 + 用于知识内容的共享 NAS；无需修改代码，也无需新建服务。操作指南：docs/deploy/small-team-recipe.md
组织模式（SSO · 中央策略 · 团队上下文 · 内部连接器）	⏸ 尚未开始	每种形态都需满足以下条件才能启动：招募到客户 + 资金到位的审计 + 维护者 ADR。部署策略说明：docs/deploy/team-deployment-posture.md

组织模式功能（SSO、中央策略、OAuth 连接器、团队上下文）按设计保持取消状态，直到招募到客户并落实安全审计资金后再启用；与此同时，小型团队指南是受支持的路径。每项功能在 team-deployment-posture 中都有一条稳定的取消记录。

---

Harness 预期

有三类安装／运行时行为看起来像是软件包缺陷，实际上属于宿主 harness 的行为，软件包无法控制：同级插件命名空间、通过 ToolSearch 显示的延迟工具，以及跨作用域技能漂移。诊断信息和软件包的应对方式：docs/contracts/harness-expectations.md。当某项技能出现两次时，请先运行 task probe:skills。

支持的工具

项目安装（npx）

工具	规则	技能	命令	工作方式
Claude Code	✅	✅	✅	读取 .claude/
Cursor	✅	—	☑️	读取 .cursor/rules/，并通过 AGENTS.md 提供命令
Cline	✅	—	☑️	读取 .clinerules/，并通过 AGENTS.md 提供命令
Windsurf	✅	—	☑️	读取 .windsurfrules，并通过 AGENTS.md 提供命令
Gemini CLI	✅	—	☑️	读取 GEMINI.md
GitHub Copilot	✅	—	☑️	读取 .github/copilot-instructions.md
Roo Code	✅	—	☑️	自动发现 .roo/rules/*.md 和 AGENTS.md
Codex CLI	✅	—	☑️	自动发现 AGENTS.md
Continue.dev	✅	—	☑️	自动发现 .continue/rules/*.md 和 AGENTS.md
Aider	📌	—	—	在 .aider.conf.yml 中手动添加 read:
Augment（VSCode/IntelliJ）	📌	—	—	仅限全局；项目会写入标记
Claude Desktop	📌	—	—	仅限全局

✅ 原生支持   ☑️ 文本引用（在 AGENTS.md 中，不能作为原生斜杠命令调用）   📌 仅标记   — 不可用

**团队可复现性：**每个通过 init 初始化的工具都会记录在 agents/installed-tools.lock 中（已提交，由机器管理）。新团队成员克隆后运行 npx @event4u/agent-config sync；CI 使用 agent-config validate 检查偏差。架构：installed-tools-manifest。

插件安装（可选，全局）

工具	安装
Augment CLI · Copilot CLI	安装 → — 规则 + 技能 + 命令，由市场自动更新

Claude Code：市场插件已弃用（单一界面 模型）。如今，npx/npm 文件投射会提供内容 和 确定性钩子 （由 agent-config global / upgrade 注册到受管理的 ~/.claude/settings.json 代码块中），因此插件只会重复列出技能/命令，而其 git-SHA 快照却会悄然过时。已有 安装：claude plugin uninstall agent-config@event4u-agent-config — agent-config doctor 会标记重复界面。

使用 agent-config upgrade（升级到最新版本）或 agent-config refresh --global（重新安装相同版本），确保全局安装保持最新；agent-config doctor 会标记缺少 PATH 二进制文件或损坏的钩子连接。请参阅 入门指南 § 保持最新 · 故障排除。

命令一览

命令	功能
agent-config init	一次性安装 — 打开浏览器向导（推荐路径或逐步设置）
agent-config init --project	初始化项目：最简 agents/ 桥接层 + 受管理的 .gitignore 代码块
agent-config config	打开配置 GUI — 全局设置中心（简单 + 高级层级、搜索、重置为默认值）
agent-config config --project	打开项目配置界面
agent-config setup	重新运行引导式入门向导（根据当前状态预填内容）
agent-config upgrade	将全局安装更新至最新版本 + 增量同步设置
agent-config doctor	只读健康状态/偏差报告

云端 / 托管 Agent 界面

对于无法运行该软件包脚本的平台，可生成供粘贴或上传的文件：

• Linear AI（Codegen、Charlie、…）— dist/linear/{workspace,team,personal}.md
• Claude.ai Web Skills — dist/cloud/<skill>.zip

→ 安装 →

---

兼容 agent-switch

agent-switch 是配套的命令行工具，可在一台机器上运行多个 Agent 账户：它会将每个账户隔离在各自的配置文件中（每个配置文件对应一个 CLAUDE_CONFIG_DIR），因此切换账户时无需先退出登录再重新登录。两者相辅相成——agent-switch 隔离账户，agent-config 管理 Agent 在账户中执行的操作。当 agent-config 在 agent-switch 配置文件下运行时，会在设置中心说明这一点，在写入共享（跨配置文件）目录前发出警告，并接受由主机提供的配置根目录，以确保其自身设置仅作用于当前配置文件。

→ 了解两者如何配合使用 →

---

适用对象

与技术栈无关的治理核心（编排 · 角色模式 · 命令集群 · 质量门禁 · 审计规范），以及针对特定技术栈的技能集：

技术栈	覆盖范围
Laravel · 现代 PHP（覆盖最深入）	Pest · PHPStan · Rector · ECS · Eloquent · Livewire/Flux · Horizon · Pulse · Reverb · Pennant
Symfony	symfony-workflow（DI · Doctrine · Messenger · voters · Twig）+ 项目分析
Next.js App Router	nextjs-patterns（RSC · Server Actions · 缓存 · 路由处理程序）+ UI react-shadcn
Zend / Laminas	项目分析 + 通用 PHP 编码／质量技能
React · Node / Express	项目分析 + UI react-shadcn
Vue · 纯 HTML	UI 指令集（vue / plain）
跨技术栈	API 设计 · 测试 · 安全 · 数据库 · Docker · Git · CI · 代码审查 · 威胁建模 · 可观测性

软件开发之外

同一编排核心也可通过 user-types/ 应用于非软件行业：galabau-field-crew · metalworking-shop · truck-driver。欢迎贡献自己的类型——5 分钟搭建模板。

---

数据治理与领域安全

三条领域安全规则（domain-safety-pii、domain-safety-disclaimer、domain-safety-retention）为约 12 个领域设定输出底线——PII 脱敏（支持／财务／招聘／营销）、建议免责声明（法律／财务／医疗／咨询）、保留期限指导（财务／支持）、运维底线（日志记录／导出）。完整的范围 → 规则 → 底线矩阵：docs/safety.md。Beta 合约：memory-visibility-v1 · decision-trace-v1。

代码来源与许可证治理

每个差异都会依据从目标仓库自身检测到的许可证推导出的许可证策略进行检查（按优先级排序；来源不一致时升级处理，绝不猜测），并由针对我们的借用台账的严格检查器（provenance/borrows.jsonl → docs/THIRD-PARTY-NOTICES.md）进行校验；若许可证属于禁止类别或未知、缺少转换说明，或说明仅称“重命名”，检查就会失败。该检查已接入 ci/ci-strict。license-compliance-audit 可按需运行相似度扫描，由人工触发，绝不由流水线触发。这是受来源治理、留有审计记录的借用规范，而非代码复制检测器。

范围与限制

• 无法在此层检测无意识地复现训练数据。 此处的任何工具——乃至任何地方的任何工具——都无法查看模型的训练数据包含什么；本系统只管理有意识地借用并记录的内容，不管控模型默默回忆起的内容。
• 在存在检测的情况下，检测范围也仅限于已知开源软件的知识库——这只是所有曾经存在过的代码中的一部分，绝不是模型的训练语料。
• 不存在面向 CI 的检测门禁。 我们构建了一个确定性扫描器（离线运行的 jscpd + 在线运行的 SCANOSS），并用冻结的合成语料对其进行测量，但它未达到预先注册的阈值（测量结果：召回率 12/16，误报 2/12，SCANOSS 仅重命名场景的召回率 0/8）——参见 docs/CLAIMS.md。它不会以任何形式在 CI 中运行，甚至不会提供提示——只能作为上述按需技能使用。
• 我们提供或评估的任何工具都无法检测仅重命名的洗白行为。 台账的转换说明检查会拒绝措辞上仅提及重命名的说明，但无法发现未披露且从未记录的仅重命名复制。

降低并记录风险——绝不消除风险。

维护者遥测（自愿启用，默认关闭）

仅在本地记录在 /implement-ticket / /work 中查阅的技能、规则和命令。通过 telemetry.artifact_engagement.enabled: true 启用；JSONL 文件保存在项目中，不会上传。报告命令：npx @event4u/agent-config telemetry:report。

上下文感知的命令建议

当提示词符合某条命令的用途时（“setze ticket ABC-123 um” → /implement-ticket），系统会将其作为带编号的选项显示——不会自动执行任何操作。按对话关闭：/command-suggestion-off。设置：.agent-settings.yml 中的 commands.suggestion.{enabled,blocklist,confidence_floor}。

---

核心原则

• 先分析，再实施——不猜测，不盲目修改
• 通过实际执行验证——不说“应该可以”
• 通过质疑促成改进——Agent 是思考伙伴，不是只会说“是”的机器
• 设计上严格把关——质量优先于灵活性
• 受治理的运行时——常驻进程需要监督、受限写入和停止控制

---

文档

文档	内容
快速入门	首次运行、3 项测试体验、配置文件、后续步骤
安装	所有安装方式、Composer/npm、编排器详情
架构	系统层、内容管线、工具支持矩阵
自定义	覆盖项、AGENTS.md、Agent 设置、成本配置文件
质量与 CI	代码检查、CI 管线、精简系统
迁移	各版本升级步骤
示例展示	更多示例和预期行为

浏览内容：所有命令 · 技能目录 · 完整目录 · llms.txt。

---

故障排除

遇到任何安装问题，首先运行：agent-config doctor——它会标出缺少于 PATH 的二进制文件、二进制文件与插件之间的版本偏差、过期的孤立项和清单问题，并针对每项提供一行修复提示。

对于“为什么规则/钩子 X 没有触发？”这类问题：运行 agent-config routing:doctor——它会以只读方式实时诊断，将每个会话启动门禁报告为 ACTIVE/INACTIVE，并附上对应事项自身给出的原因（例如：session-canary: ACTIVE for "Alex" 与 INACTIVE — no name on any settings layer）、平台的事项链、宿主钩子注册情况，以及路由器和投影的新鲜度。若要查看更深入的钩子内部信息（失败时放行/关闭策略、各事项最近一次调度器反馈）：运行 agent-config hooks:doctor。

升级和过期问题——升级后命令或技能缺失、技能重复出现、升级中断、command not found、项目文件过期：参见 docs/troubleshooting.md § 升级和过期问题。

---

开发

要处理软件包本身？编辑 src/（唯一可信来源——src/skills、src/rules、src/agent-src/），然后重新生成目录树：

task sync             # regenerate dist/agent-src/ and .augment/
task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
task ci               # full pipeline — green before PR
task test             # unit + integration tests
task dev:setup        # boot the onboarding wizard against the working tree

**从源码检出目录调用 CLI：**使用 ./agent-config <command>（仓库根目录下的维护者脚本 → scripts/agent-config → dist/cli/agent-config.js）。在源码仓库中，如果之前没有运行过 npm link，npx @event4u/agent-config 将无法解析，因为没有 node_modules/.bin/agent-config 符号链接——请改用 ./agent-config。如果缺少 dist/cli/agent-config.js，请使用 npm run build:cli 构建 TS 二进制文件。

→ 完整的项目结构和命令： docs/development.md · CONTRIBUTING.md。技术栈：全程使用 TypeScript——CLI、UI 以及构建 / lint 脚本。MCP 注册表负载会生成到 dist/mcp/ 中（提交清单）。

---

要求

• Node ≥ 22.6——npx @event4u/agent-config init 是标准安装方式。整个安装过程中不需要 Python（TypeScript 迁移后，Python 安装程序已退役）。
• **平台：**macOS 12.3+、Linux、WSL2。Git Bash 需要启用开发者模式才能使用符号链接。重建 .augment/ 的贡献者还需要安装 Task。

Windows

不支持使用原生 PowerShell / cmd 安装文件——完整安装目录树请使用 WSL2。Windows 原生环境支持的范围是 MCP stdio 服务：将任意 MCP 客户端指向

npx -y @event4u/agent-config mcp-server

即可使用治理内容（提示词、资源、工具），无需安装文件。将 bash 调度器移植到原生 Windows 取决于需求：如果有具名的 Windows 用户无法使用 WSL2 或 MCP 路径，就会重新启动该工作（参见 agents/roadmaps/——road-to-credible-install Phase 3）。

资助

该软件包免费，采用 MIT 许可，并将一直如此——没有付费层级，也没有双重许可。如果它为你节省了时间，而你想出一份力，可以通过仓库顶部的 GitHub Sponsor 按钮进行资助。这就是全部方式。如果你不想资助，也可以照常使用；这里没有任何内容会因此受到限制。

许可证

MIT。

mcp-name: io.github.event4u-app/agent-config