consensus-rnd CLAUDE.md

consensus-rnd - Agent 工作指南

本文件给在本仓库内维护 skill、清单和文档的 agent 使用，不是下游 host 的运行时配置。仓库定位与共识引擎设计哲学见英文 canonical README.md，中文 companion 见 README.zh-CN.md。

旁路推理通道: nyxid oracle (ChatGPT Pro)

nyxid oracle 可作为 codex / Claude 之外的独立推理通道。命令、参数和输出字段以 nyxid oracle --help 为准；长 prompt 可用 --file -，多轮可用 --new-conversation / --conversation。异步请求只在完成后读取一次结果，不 busy-loop 轮询。oracle 能自行抓取公开可访问的 GitHub 链接，所以大段仓库内容可改为附 pin 到 commit SHA 的 permalink，而不是塞进 prompt；未公开的内容不得外链，也不得为了外链而推送或改仓库可见性。

仓库性质

这是一个跨平台 Agent Skills 发布仓库，不是应用代码仓库。唯一产物是 skills/<name>/ 下的 SKILL.md 及其配套文件，同一份 skills/ 由 Claude Code / Codex / Cursor / Gemini 共享。

目录约定

.
├── .claude-plugin/        # Claude Code: plugin.json + marketplace.json
├── .codex-plugin/         # Codex: plugin.json
├── .cursor-plugin/        # Cursor: plugin.json
├── gemini-extension.json + GEMINI.md
├── package.json           # npm 风格元数据 / 版本锚点
├── AGENTS.md -> CLAUDE.md # 跨 agent 约定(符号链接)
├── README.md + README.zh-CN.md
├── LICENSE
├── skills/sshx/           # 发布的 worker-delegated inline consensus skill
└── .version-bump.json     # 版本号同步映射

设计哲学(跨 skill 不动点)

• 单一主干、插件扩展：每个 skill 只有一条权威主链路，新能力挂载在明确的子模块或脚本上。
• 内核最小化：SKILL.md 承载触发条件、稳定不变量、行为合同和事实源索引；机械部分下沉到 scripts/，prompt 模板下沉到 prompts/。
• 边界清晰、职责分层：本文件承载仓库级边界；skill 的工作流细则和术语归其自身事实源维护。
• 事实源唯一：版本号以 .version-bump.json 为准，skill 行为以对应 SKILL.md 和测试为准，host 事实由 host 配置注入。
• 抽象优先、行为契约：跨 skill 只通过稳定文件 artifact、host 配置等边界协作，不耦合内部实现。
• 强类型边界、窄扩展点：扩展点必须有清楚职责、最小权限和可验证的授权来源，不引入通用生命周期权力。
• 抽象一旦能被滥用即设计未完成；删除优先，废弃路径直接移除，不保留兼容空壳或历史副本。
• 变更必须可验证：优先用 behavior test 或端到端可观察输入 / 输出 / 副作用断言；source-regression 只锁跨 artifact 一致性、事实源唯一性和授权边界。
• 治理前置：架构性或流程性规则必须和机械验证手段同时进入仓库。
• 正确架构优先：随着 skill 增长若边界自然变松，应重设计而非增加 escape hatch。
• 命名跟随职责：被脚本解析或跨 agent 传递的名字由所属事实源声明格式、canonical write policy 和迁移策略。
• 哲学文档不写 schema/identifier 版本后缀；Release semver 只作为 .version-bump.json 的发布坐标。

共识引擎哲学

权威表述见英文 canonical README.md 的 Core 段；中文 companion 为 README.zh-CN.md。