@weotro/dx 0.3.6 → 0.3.8

package/lib/codex-initial.js

@@ -15,6 +15,7 @@ const REMOVED_AGENT_REFERENCES = ['ship-issue-pr-core.md']
 const DELETED_SKILLS = [
   'ask_cc',
   'delegate-cc',
+  'doctor',
   'oo-ship-issue-pr',
   'cc-ship-issue-pr',
   'autospec',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/ask_3th/SKILL.md

@@ -1,29 +1,17 @@
 ---
 name: ask_3th
-description: 显式调用 ask_3th 或被已授权流程调用时，向第三方提问、咨询或获取独立审查意见。
+description: 显式调用 ask_3th 或被已授权流程调用时，提问、咨询或获取独立审查意见；默认使用当前运行时的 fresh subagent，用户指定其他运行时时使用指定通道。
 ---
 
 # ask_3th
 
-向第三方获取答案或第二意见，咨询与审查只读。调用方提供问题、必要事实、源码或 diff、约束和预期输出；运行时选择、调用与失败回退由本技能负责，调用方只接收最终结果和执行说明。
+默认直接新建当前运行时的 fresh subagent（refresh subagent），继承当前模型，以独立上下文提供答案或第二意见。咨询与审查只读。默认路径不检查运行时或外部工具；用户明确指定其他运行时时，按指定通道调用。
 
 ## 执行流程
 
-1. 整理自包含的问题材料，排除凭据。审查材料覆盖请求范围，证据不足时先补充，不假定咨询者拥有当前对话。
-2. 读取 [delegate_3th](../delegate_3th/SKILL.md)，使用其 `consult` 模式完成运行时判断：Codex 宿主调用 Claude，Claude Code 宿主调用 Codex。按相应通道调用，咨询不授予写权限。
-3. 第三方调用失败时，立即执行该技能的 fresh sub-agent 回退流程，等待实质答案后返回。回退在本技能内部完成，不把中间的 `fallback_required` 当作最终答复交给调用方。
-4. 核实答案回应原问题，按依赖技能的返回契约交付答案、实际执行者及回退说明。独立审查使用未参与实现或修复的全新会话。
+1. 整理自包含的问题材料，包含问题、必要事实、源码或 diff、约束和预期输出，排除凭据。审查材料覆盖请求范围，证据不足时先补充，不假定咨询者拥有当前对话。
+2. 用户明确指定其他运行时时，读取 [指定运行时调用](../delegate_3th/references/external-runtimes.md)，以 `consult` 模式使用该通道；否则直接使用当前会话的原生 subagent 工具创建全新执行者。使用 `spawn_agent` 时设置 `fork_turns: "none"`，省略 `model`、`reasoning_effort` 和 `agent_type`；使用 `Agent` 时新建 `general-purpose` 会话，省略 `model`，不 resume 旧会话。独立审查者必须未参与本次实现或修复；即使当前执行者已是 subagent，也需要新建独立执行者。
+3. 传入自包含的问题材料，限定只读，要求执行者自行回答，不把同一问题再次交给 `ask_3th` 或 `delegate_3th`。
+4. 等待同一执行者返回实质答案，核实是否回应原问题，再交付答案、关键依据、不确定性及实际执行者和会话 ID。静默或单次等待超时不等于失败；用户取消时停止。工具不可用、达到嵌套限制或执行失败时，如实报告阻塞；未经用户授权，不更换运行时或无限新建 agent。
 
-用户要求修改代码或执行任务时，转入 `delegate_3th` 的 `task` 模式，沿用已有任务范围与授权。
-
-## Claude 通道脚本
-
-仅在上述路由选择 Claude 时使用当前技能目录的 `scripts/ask_3th.py`；它固定为咨询模式，调用细节与失败状态由 `delegate_3th` 维护。脚本自身不能启动宿主 sub-agent，收到失败状态后由执行本技能的 agent 完成回退。
-
-在 Codex 宿主下默认不传模型参数，由 Claude Code CLI 按当前生效的用户/项目配置及环境变量选择模型。调用方不要补上固定模型 ID；返回中的 `requested_model: null` 表示使用 CLI 默认选择，实际模型未知时不要推测。
-
-```bash
-python3 "$HOME/.agents/skills/ask_3th/scripts/ask_3th.py" --prompt-file /绝对路径/问题.txt
-```
-
-`--timeout` 是无活动告警阈值（默认 120 秒），不是答复截止时间。通过宿主异步工具持续读取同一会话；静默或单次等待超时本身不算调用失败。
+用户要求修改代码或执行任务时，转入 [delegate_3th](../delegate_3th/SKILL.md) 的 `task` 模式，沿用已有任务范围与授权。

package/skills/delegate_3th/SKILL.md

@@ -1,89 +1,41 @@
 ---
 name: delegate_3th
-description: 显式调用 delegate_3th 或被已授权流程调用时，委托第三方执行任务；内部选择 Claude 或 Codex，失败后由 fresh sub-agent 接续并返回结果。
+description: 显式调用 delegate_3th 或被已授权流程调用时，委托执行任务并验收结果；默认使用当前运行时的 fresh subagent，用户指定其他运行时时使用指定通道。
 ---
 
 # delegate_3th
 
-本技能负责第三方运行时路由、调用、失败回退及验收。调用方提供任务并接收最终结果，不需要选择 CLI、模型或接管方式。`ask_3th` 使用这里的 `consult` 模式；委托开发工作使用 `task` 模式。
+默认直接新建当前运行时的 fresh subagent（refresh subagent），继承当前模型，以独立上下文执行任务。默认路径不检查运行时或外部工具；用户明确指定其他运行时时，按指定通道调用。
 
 ## 1. 准备交接
 
-遵循宿主指令、当前任务要求与已有授权、目标项目适用的 AGENTS.md。保留现有认证，任务授权不因切换执行者而扩大，权限拒绝不能靠回退绕过。
+遵循当前任务要求、已有授权和目标项目适用的 AGENTS.md。任务授权不因切换执行者而扩大。
 
-- **咨询 `consult`**：提供问题、事实、源码或 diff、约束与预期输出，只读；Claude CLI 不开放工具，Codex 通道与回退执行者仅允许必要的只读检索。
-- **执行 `task`**：任务书包含工作目录、目标、责任文件或模块、项目指令、已有成果、验收标准和实际验证命令。告知执行者还有其他协作者，保留他人改动，只处理分配范围。
+- **咨询 `consult`**：按 [ask_3th](../ask_3th/SKILL.md) 的只读流程处理，并传递用户指定的运行时。
+- **执行 `task`（默认）**：任务书包含工作目录、目标、责任文件或模块、项目指令、已有成果、验收标准和实际验证命令。告知执行者还有其他协作者，保留他人改动，只处理分配范围。
 
-执行前检查 `git status --short`、相关 diff 和未跟踪文件，记录基线。分配互不重叠的文件；需要隔离时使用独立 worktree，并带入任务所需的未提交版本。原执行者仍在工作时，其他执行者不修改其责任文件。
+执行任务前检查 `git status --short`、相关 diff 和未跟踪文件，记录基线。分配互不重叠的文件；需要隔离时使用独立 worktree，并带入任务所需的未提交版本。原执行者仍在工作时，其他执行者不修改其责任文件。
 
-将必要上下文写入本次临时 UTF-8 任务文件，排除凭据。默认只授权本地实现与验证；调用方明确委托独立 Issue 的完整交付时，任务书须带上该授权与 `ship-issue-pr` 流程，才可执行对应 Git/GitHub 操作。
+在任务书中提供必要上下文和用户指定的运行时，排除凭据。默认只授权本地实现与验证；调用方明确委托独立 Issue 的完整交付时，任务书须带上该授权与 `ship-issue-pr` 流程，才可执行对应 Git/GitHub 操作。
 
-## 2. 在技能内部选择运行时
+## 2. 调用执行者
 
-依据当前会话宿主和实际暴露的工具判断，不根据模型名称或本机安装了哪些 CLI 猜测，也不要求调用方选择。
+用户明确指定其他运行时时，读取 [指定运行时调用](references/external-runtimes.md)，以 `task` 模式使用该通道。未指定或指定当前运行时时，直接执行以下 fresh subagent 流程，无需探测宿主、模型配置或已安装的 CLI。
 
-| 当前宿主 | 第三方通道 |
-| --- | --- |
-| Codex | 下文 Claude CLI |
-| Claude Code | 下文 Codex 插件 |
-| 宿主无法确定或对应通道缺失 | 直接进入 fresh sub-agent 回退 |
+fresh subagent 指本次新建、独立上下文的执行者，不复用当前 agent 或此前的实现/审查会话。即使本技能当前由 subagent 执行，也应新建执行者。
 
-每次请求只尝试选定的第三方一次。调用失败后立即回退，不换另一个 Claude 模型、不重试另一条外部通道。单次等待超时、静默告警或任务尚未返回不等于失败；用户取消则停止，不启动接续任务。
+1. 使用当前会话的原生 subagent 工具，采用默认通用角色并继承当前模型，不设置模型覆盖。使用 `spawn_agent` 时设置 `fork_turns: "none"`，省略 `model`、`reasoning_effort` 和 `agent_type`；使用 `Agent` 时新建 `general-purpose` 会话，省略 `model`，不 resume 旧会话。
+2. 传入自包含任务书，要求直接处理分配工作，不将同一工作再次交给 `ask_3th` / `delegate_3th`。完整交付中的后续独立咨询或审查仍按交付流程调用技能，审查者不得是原实现者。
+3. 保存 subagent ID，持续等待同一任务完成。静默或单次等待超时不等于失败；用户取消时停止。工具不可用、达到嵌套限制或执行失败时，如实返回已完成成果、未完成项与具体阻塞；未经用户授权，不更换运行时或无限新建 agent。
 
-### Claude CLI
+## 3. 验收与返回
 
-需要 `python3` 和已认证的 `claude`；`dx initial` 只同步技能文件。使用当前技能目录的脚本，默认安装示例：
+对照基线、完整 diff、责任范围及验收标准核查结果，运行必要测试，复用仍有效的验证证据。报告包含权限拒绝时，核实缺失项并保留权限边界。执行者的成功声明不等于验收通过。
 
-```bash
-# 咨询，无活动告警阈值默认 120 秒。
-python3 "$HOME/.agents/skills/delegate_3th/scripts/delegate_3th.py" --prompt-file /绝对路径/问题.txt
+向调用方返回实际变更、验证结果和未完成项，并附：
 
-# 执行，无活动告警阈值默认 900 秒。
-python3 "$HOME/.agents/skills/delegate_3th/scripts/delegate_3th.py" --mode task --cwd /绝对路径/工作区 --prompt-file /绝对路径/任务.txt
-```
+- `requested_provider`：用户指定的运行时，未指定则为当前运行时。
+- `actual_executor`：实际运行时及 subagent / job ID；默认 subagent 继承当前模型，外部通道模型未知时不推测。
+- `status`：验收通过为 `completed`；仍有缺口为 `blocked`，说明恢复所需条件。
 
-默认不传 `--model`，由 Claude Code CLI 使用该次调用实际生效的用户/项目配置及环境变量选择模型；技能不硬编码模型，也不读取或覆盖模型配置。Codex 宿主下的咨询与执行均遵循此规则，用户调整 Claude Code 默认模型后，后续调用随之生效。
-
-仅在用户明确指定本次任务模型时，使用任务模式的 `--start-model <模型 ID 或别名>`；脚本将其原样传给 Claude 的 `--model`，不限制固定模型名单，也不构成重试链。需要运行验证命令时按已有授权追加具体的 `--allow-command '仓库实际验证命令'`，可重复传入。
-
-执行模式开放 `Read,Glob,Grep,Edit,Write,Bash`，使用 `acceptEdits`，无法获批的工具请求自动拒绝；现有权限规则继续生效，允许命令不是独立沙箱。两种模式关闭 hooks、MCP 和技能，因此任务书必须包含必要项目规则。脚本默认仅执行本地开发；完整交付等超出该边界的任务直接进入 fresh sub-agent，由其承接明确授权。
-
-通过宿主异步工具保留会话 ID 并持续读取结果，至少每 60 秒汇报有意义的进度。`--timeout` 只控制无活动告警，不自动终止任务。脚本通过输出字节和 Git 跟踪及未忽略文件的变化观察活动；忽略目录产物需另查，观测不可用不代表停滞。
-
-脚本 stdout 返回单个 JSON：`ok` 表示咨询已返回，`review_required` 表示任务报告待验收，`fallback_required` 表示立即进入下文回退。`requested_model: null` 表示未覆盖 CLI 模型配置，不能据此声称实际使用了某个模型；显式指定时记录该请求值。脚本只报告失败，启动宿主 sub-agent 和等待结果是本技能执行者的职责。
-
-### Codex 插件
-
-使用当前 Claude Code 会话实际暴露的 Codex 插件能力：任务或咨询可用 `Agent(subagent_type: "codex:codex-rescue")`；普通审查可用 companion 的 `review`，挑战方案假设可用 `adversarial-review`。选择符合当前请求的一条通道，只读或写入范围写入任务书。
-
-companion 使用实际安装路径；需要定位时仅检查当前 Claude 配置目录对应的 marketplace/cache，以 `scripts/codex-companion.mjs --help` 核实参数，不硬编码缓存版本。审查示例：
-
-```bash
-node "<plugin-root>/scripts/codex-companion.mjs" review --wait --base "<actual-base>"
-```
-
-保存 job/agent ID、工作目录与输出位置，异步等待同一任务。插件缺失、启动失败、认证或额度错误、非零退出、明确失败报告或无效结果均进入回退。
-
-## 3. 失败后立即交给 fresh sub-agent
-
-fresh sub-agent（refresh subagent）指本次新建、独立上下文的执行者，不复用当前 agent 或此前的实现/审查会话。即使本技能当前由 sub-agent 执行，也应新建执行者，不能直接由它自称 fresh 后接手。
-
-1. 确认原调用及其写进程已停止；仍在运行时先检查会话、子命令和权限等待，确认实际失败或无法推进后终止并核实停止。用户取消不触发回退。
-2. 检查现有 diff、测试与外部副作用，将已完成成果和剩余工作加入任务书，避免从头重放。保留原权限限制与只读/写入边界。
-3. 立即创建一个使用宿主默认模型的全新 sub-agent：Codex 使用 `spawn_agent`，设置 `fork_turns: "none"`；Claude Code 使用新的 `Agent(subagent_type: "general-purpose")`，不 resume 旧会话。传入自包含任务书，要求直接处理本次失败调用的剩余工作，不将同一工作再次交给 `ask_3th` / `delegate_3th` 或外部 CLI，避免递归回退。完整交付中的后续独立咨询/审查仍按交付流程调用技能。独立审查者不得是原实现者。
-4. 等待该 sub-agent 完成并验收其结果，再向调用方返回。若 sub-agent 工具不可用、达到嵌套限制或回退也失败，如实返回未完成项与具体阻塞；不冒充已接管或已完成，也不无限创建新 agent。
-
-## 4. 验收与返回
-
-咨询确认获得实质答案；执行对照基线、完整 diff、责任范围及验收标准核查，运行必要测试，复用仍有效的验证证据。`permission_denials` 非零或报告包含权限拒绝时，核实缺失项并保留权限边界。第三方成功声明不等于验收通过。
-
-向调用方返回答案或实际变更、验证结果、未完成项，并附简短执行说明，包含：
-
-- `requested_provider`：原定 Claude、Codex，或宿主未知。
-- `actual_executor`：实际第三方及请求模型（可得时），或 fresh sub-agent 及其 ID。
-- `fallback_used` 与 `fallback_reason`：是否回退及具体原因；未回退时注明无。
-- `status`：验收后为 `ok` / `completed`，仍有缺口为 `blocked`，并说明恢复所需条件。
-
-例如：“Claude 调用因额度不足失败，已由 fresh sub-agent <ID> 完成；验证通过。”这段说明供调用方记录，运行时与回退决策已在本技能内完成。请求模型 ID 不保证服务端未切换模型。
-
-清理本次临时任务文件；保留仍有成果待整合的 worktree。
+保留仍有成果待整合的 worktree。

package/skills/delegate_3th/references/external-runtimes.md

@@ -0,0 +1,43 @@
+# 用户指定的外部运行时
+
+仅在用户明确要求使用其他运行时时读取本文件。按用户指定的目标选择通道，不自动采用“Codex 调 Claude、Claude 调 Codex”的反向路由。当前会话已明确的运行时信息直接使用，不额外探测；用户只说“另一个运行时”且目标无法从上下文确定时，再澄清目标。
+
+沿用调用方的 `consult` / `task` 模式、任务范围与权限边界，提供自包含任务书。咨询与独立审查只读，审查会话必须未参与实现或修复。
+
+## Claude Code
+
+使用已认证的 `claude` 和技能目录的 Python 脚本。`dx initial` 只同步技能文件，不安装或认证 CLI。
+
+```bash
+# 咨询
+python3 "$HOME/.agents/skills/ask_3th/scripts/ask_3th.py" --prompt-file /绝对路径/问题.txt
+
+# 本地任务
+python3 "$HOME/.agents/skills/delegate_3th/scripts/delegate_3th.py" --mode task --cwd /绝对路径/工作区 --prompt-file /绝对路径/任务.txt
+```
+
+使用实际技能目录路径。将任务材料写入临时 UTF-8 文件，排除凭据。默认不传模型参数，由 Claude Code CLI 使用当前生效的配置；仅用户明确指定任务模型时传 `--start-model <模型 ID 或别名>`。需要验证命令时按已有授权追加具体的 `--allow-command '仓库实际验证命令'`，可重复传入。
+
+咨询模式不开放工具，所需证据先放入问题材料。任务模式开放 `Read,Glob,Grep,Edit,Write,Bash`，采用 `acceptEdits`，无法获批的工具请求自动拒绝；现有权限规则继续生效，允许命令不是独立沙箱。两种模式关闭 hooks、MCP 和技能，任务书必须包含必要项目规则。脚本仅支持本地开发与验证；指定 Claude 执行完整 Git/GitHub 交付时，如实报告该通道限制，不自动换运行时。
+
+通过宿主异步工具保留会话 ID，持续读取同一调用。`--timeout` 是无活动告警阈值，咨询默认 120 秒，任务默认 900 秒，不是执行截止时间；静默或单次等待超时不构成失败。
+
+stdout 返回 JSON：`ok` 表示咨询已返回，`review_required` 表示任务报告待验收。`requested_model: null` 表示使用 CLI 默认配置，不能据此推测实际模型。`permission_denials` 非零时核实未完成项。`fallback_required` 是旧脚本的失败信号，不代表已获得切换运行时的授权；按下文处理失败。
+
+## Codex
+
+使用当前会话已暴露的 Codex 插件能力：咨询或任务可用 `Agent(subagent_type: "codex:codex-rescue")`；普通审查可用 companion 的 `review`，挑战方案假设可用 `adversarial-review`。选择符合用户请求的通道，明确只读或写入范围。
+
+companion 使用实际安装路径；仅在需要该通道且路径未知时，在当前 Claude 配置目录对应的 marketplace/cache 中定位，以 `scripts/codex-companion.mjs --help` 核实参数，不硬编码缓存版本。
+
+```bash
+node "<plugin-root>/scripts/codex-companion.mjs" review --wait --base "<actual-base>"
+```
+
+保存 job/agent ID、工作目录与输出位置，异步等待同一任务。若指定通道不可用，如实报告阻塞。
+
+## 失败与交付
+
+每次请求只尝试指定通道一次。调用失败时报告具体原因、已有成果与未完成项，保留用户指定的运行时；只有用户已授权失败后使用当前运行时，才启动 fresh subagent 接续。接续前确认原调用及其写进程已停止，检查当前 diff 和外部副作用，将剩余工作交接，避免重复执行。权限拒绝不能通过换执行者绕过，用户取消不触发接续。
+
+返回实质答案或任务报告，由调用方验收，并注明请求运行时、实际执行者和会话 ID；发生已授权的接续时附原因。清理临时任务文件，保留待整合成果。

package/skills/online-debug-guard/SKILL.md

@@ -8,6 +8,7 @@ description: 仅在显式调用 online-debug-guard 时使用：远程在线调
 ## 执行边界与优先级
 
 在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+默认在当前执行模式下直接排查、修复并验证，不主动切换 Plan 模式或把计划审批作为开工条件；用户明确要求先规划时遵从。根据证据自主选择下一步，持续推进到问题解决，或遇到需要用户补充信息或授权的具体阻塞。
 只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
 仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
 
@@ -15,7 +16,7 @@ description: 仅在显式调用 online-debug-guard 时使用：远程在线调
 
 从当前任务、已有连接信息、项目配置和 SSH Host 推断目标环境，接受项目的环境别名（如 `prod1`、`test`）。先读相关配置核实映射；目标仍不唯一时继续本地定位，在连接不明确的远程主机前询问。未知环境不默认当作 development。
 
-生产环境的已授权只读取证不依赖 Plan 模式。连接优先使用项目指定的 SSH Host；`zh-ai-prod`、`ai-staging` 仅是已有项目的示例，使用前核实实际配置。
+连接优先使用项目指定的 SSH Host。按目标读取已核实的部署位置、env 路径和只读连接示例：`zh-ai-prod` 使用 [zh-ai-prod 指南](references/zh-ai-prod.md)，`br-ai-prod` 使用 [br-ai-prod 指南](references/br-ai-prod.md)；其他主机按实际部署定位。
 
 ## 取证
 

package/skills/online-debug-guard/references/br-ai-prod.md

@@ -0,0 +1,98 @@
+# br-ai-prod：环境文件与数据库连接
+
+2026-10-06 通过 SSH 只读核实。使用前重新核对 PM2 状态和 `current` 指向，尤其不要仅凭主机名推断应用环境。
+
+## 连接与应用定位
+
+使用本机 SSH 别名，登录用户为 `ubuntu`；地址和密钥由 SSH 配置提供。
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=10 br-ai-prod
+pm2 list
+pm2 describe backend-br
+readlink -f /home/ubuntu/work/ai-monorepo/current
+```
+
+| 项目 | PM2 进程 | 核实状态 | 部署根目录 | env 环境 |
+| --- | --- | --- | --- | --- |
+| ai-monorepo | backend-br | online | /home/ubuntu/work/ai-monorepo | production |
+| kol | kol-api、kol-worker | online | /home/ubuntu/work/kol | production |
+| paycenter | paycenter-backend | stopped | /home/ubuntu/work/paycenter | staging |
+
+三个项目的 `current` 都指向各自 `releases/<版本目录>`；核实当天与 PM2 cwd 一致。`paycenter` 的停止状态不是本任务要求修复的问题，不要为了连接数据库而启动服务。
+
+此主机的 `node` 和 `pm2` 来自 `/home/ubuntu/work/ai-monorepo/runtime/bin/`。若非交互 SSH 的 PATH 缺少它们，可在该会话执行：
+
+```bash
+export PATH=/home/ubuntu/work/ai-monorepo/runtime/bin:$PATH
+```
+
+核实时 PATH 中没有 `psql`，可直接复用主应用发布包中的 `pg`，无需安装客户端。
+
+## env 在哪里
+
+真实配置位于部署根目录的 `shared` 中，`current` 内同名文件通过符号链接引用：
+
+| 项目 | 基础文件 | 覆盖文件 |
+| --- | --- | --- |
+| ai-monorepo | /home/ubuntu/work/ai-monorepo/shared/.env.production | /home/ubuntu/work/ai-monorepo/shared/.env.production.local |
+| kol | /home/ubuntu/work/kol/shared/.env.production | /home/ubuntu/work/kol/shared/.env.production.local |
+| paycenter | /home/ubuntu/work/paycenter/shared/.env.staging | /home/ubuntu/work/paycenter/shared/.env.staging.local |
+
+忽略 `.before-*` 等备份文件。凭据只在服务器进程内读取，不输出整份 env 或 `pm2 jlist`，不把连接串放入命令参数或文档，不直接 `source` dotenv 文件。
+
+- `ai-monorepo`、`paycenter`：使用 `dotenv` 解析两层文件，以 `.local` 覆盖基础文件，再用 `dotenv-expand` 展开变量。数据库使用 `DATABASE_URL`，Redis 使用 `REDIS_URL`。
+- `kol`：复用 `/home/ubuntu/work/kol/current/env-file.cjs` 的 `loadEnv(directory, environment)`。它使用 Node `util.parseEnv` 合并两层配置并校验未填写的占位符，不做 dotenv 变量展开。数据库字段是 `DATABASE_DSN`，核实时为 PostgreSQL URL；不要误用 `DATABASE_URL`。该项目没有自己的 Node 依赖目录。
+
+核实当天，主应用与 paycenter 的数据库、Redis 文件配置展开后与 PM2 保存的配置一致；kol 的 `DATABASE_DSN` 与两个运行进程的 PM2 配置一致。后续配置可能变化，需要时在服务器内比较，只输出比较结果。
+
+## PostgreSQL 只读连接
+
+主应用可直接在 **br-ai-prod 的 SSH 会话**中运行 [zh-ai-prod 指南的 PostgreSQL 示例](zh-ai-prod.md#postgresql-只读连接)：客户端目录与 `project = 'ai-monorepo'` 相同，连接目标取自本机 env。核实当天返回 `ok: 1`、`read_only: 'on'`。
+
+kol 使用它自己的配置加载器，同时借用主应用的 `pg` 客户端。以下在 br-ai-prod 服务器执行，仅检查连通性，不查询业务数据：
+
+```bash
+cd /home/ubuntu/work/ai-monorepo/current
+node <<'NODE'
+const { Client } = require('pg');
+const { loadEnv } = require('/home/ubuntu/work/kol/current/env-file.cjs');
+let client;
+(async () => {
+  const env = loadEnv('/home/ubuntu/work/kol/current', 'production');
+  if (!env.DATABASE_DSN) throw new Error('DATABASE_DSN_MISSING');
+  client = new Client({
+    connectionString: env.DATABASE_DSN,
+    connectionTimeoutMillis: 5000,
+    statement_timeout: 5000,
+    options: '-c default_transaction_read_only=on',
+  });
+  await client.connect();
+  await client.query('BEGIN READ ONLY');
+  const result = await client.query(
+    "SELECT 1 AS ok, current_setting('transaction_read_only') AS read_only",
+  );
+  console.log(result.rows);
+  await client.query('ROLLBACK');
+})().catch(error => {
+  console.error('数据库检查失败:', error.code || error.name);
+  process.exitCode = 1;
+}).finally(async () => {
+  if (client) await client.end();
+});
+NODE
+```
+
+kol 示例已在核实当天实际运行，返回 `ok: 1`、`read_only: 'on'`。
+
+paycenter 本次只核实配置路径，未连接数据库。任务确实涉及它时，使用主应用示例的客户端依赖，将项目改为 `paycenter`，并将读取的文件名改为 `.env.staging`、`.env.staging.local`；不能套用 production 文件名。
+
+## Redis
+
+主应用和 paycenter 配置了 `REDIS_URL`，可复用主应用的 `ioredis`，连接参数从对应项目的 env 解析取得。设置有限超时、禁用自动重连，检查时只发 `PING`，结束后断开。本次未测试 Redis 连通性；kol 配置中未发现 Redis 字段。
+
+后续业务取证保持查询范围有限，SQL 使用参数化查询；数据库写入、Redis 删除或服务重启仍遵循技能中的授权边界。
+
+## Prometheus
+
+该服务器已安装 Prometheus，并由 PM2 进程 `prometheus` 管理。调试指标入口、配置、数据目录和查询方法见 [Prometheus 调试参考](prometheus.md)。

package/skills/online-debug-guard/references/prometheus.md

@@ -0,0 +1,82 @@
+# Prometheus 调试参考
+
+`zh-ai-prod` 与 `br-ai-prod` 的 Prometheus 配置在 2026-10-11 通过 SSH 只读核实。使用前仍需检查进程状态和目标健康度。
+
+## 运行位置
+
+- PM2 进程：`prometheus`，脚本 `/usr/local/bin/prometheus`
+- 配置：`/etc/prometheus/prometheus.yml`（root 持有，权限 `644`）
+- TSDB：`/var/lib/prometheus`
+- Web/API：`127.0.0.1:9090`，只绑定本机
+- 数据保留：`45d`
+- PM2 日志：`/home/ubuntu/.pm2/logs/prometheus-out.log`、`prometheus-error.log`
+
+两台服务器均使用以下启动参数：
+
+```text
+--config.file=/etc/prometheus/prometheus.yml
+--storage.tsdb.path=/var/lib/prometheus
+--storage.tsdb.retention.time=45d
+--web.listen-address=127.0.0.1:9090
+```
+
+不要把 9090 直接暴露到公网。远程查询时优先 SSH 到目标机，或使用经过授权的 SSH 隧道；不要为了调试修改监听地址或防火墙。
+
+## 已配置的采集目标
+
+配置中的抓取间隔和目标如下：
+
+| job | 地址 | 内容 |
+| --- | --- | --- |
+| `ai-backend` | `127.0.0.1:9465/metrics` | 应用指标 |
+| `host-node` | `127.0.0.1:9100/metrics` | Node Exporter 主机指标 |
+| `host-processes` | `127.0.0.1:9256/metrics` | Process Exporter 进程指标 |
+
+Node Exporter 和 Process Exporter 也由系统进程运行，监听本机地址。Prometheus 与三个目标的核实状态均为 `up`；目标可能随部署变化，先查询 API，不要只依赖这份文档。
+
+## 先做健康检查
+
+```bash
+pm2 describe prometheus
+pm2 logs prometheus --lines 200 --nostream
+curl -fsS --max-time 3 http://127.0.0.1:9090/-/ready
+curl -fsS --max-time 3 http://127.0.0.1:9090/api/v1/targets
+```
+
+`/api/v1/targets` 返回 JSON，重点看 `activeTargets[].labels.job`、`health`、`lastError`、`lastScrape` 和 `scrapeUrl`。输出诊断时保留 job、状态和错误摘要，不要把无关完整 JSON 或环境变量带出。
+
+查看当前启动参数和存储权限：
+
+```bash
+p=$(pgrep -xo prometheus)
+tr '\0' ' ' < /proc/$p/cmdline; echo
+stat -c '%U %G %a %n' /etc/prometheus/prometheus.yml /var/lib/prometheus
+```
+
+## 查询指标
+
+Prometheus API 只读查询使用 `query` 参数。先用短时间范围和明确指标名，避免高基数的全量查询：
+
+```bash
+curl --get -fsS --max-time 5 http://127.0.0.1:9090/api/v1/query \
+  --data-urlencode 'query=up'
+
+curl --get -fsS --max-time 5 http://127.0.0.1:9090/api/v1/query \
+  --data-urlencode 'query=process_resident_memory_bytes{job="host-processes"}'
+```
+
+后端应用是否暴露指标，先直接检查：
+
+```bash
+curl -fsS --max-time 3 http://127.0.0.1:9465/metrics | head -80
+```
+
+再按指标名查询。不要把用户提供的内容直接拼入 PromQL；标签值使用 URL 编码，复杂表达式先在本地构造后审核。
+
+Prometheus 适合确认服务是否存活、请求量、延迟、错误率、CPU、内存、进程重启和抓取失败。它不是应用日志库；需要堆栈、请求参数或业务错误时，回到对应 PM2 日志和应用日志。
+
+## 时间范围与数据限制
+
+默认 API 查询为即时值。需要趋势时使用 `/api/v1/query_range`，明确 `start`、`end`、`step`，时间窗先控制在问题发生前后，避免一次拉取 45 天数据。TSDB 查询和统计只读，不修改 Prometheus 数据。
+
+若指标缺失，按顺序检查：应用 `/metrics`、目标 `health` 和 `lastError`、Prometheus 日志、PM2 进程状态、应用部署版本。不要直接删除 `/var/lib/prometheus`；TSDB 删除会丢失历史证据，属于不可逆操作。

package/skills/online-debug-guard/references/zh-ai-prod.md

@@ -0,0 +1,106 @@
+# zh-ai-prod：环境文件与数据库连接
+
+2026-10-06 通过 SSH 只读核实。以下是该主机的部署约定，使用前核对 PM2 当前进程和 `current` 指向；不要套用到其他服务器。
+
+## 连接与应用定位
+
+使用本机 SSH 配置中的别名，登录用户为 `ubuntu`。主机地址和密钥由 SSH 配置提供，不复制到技能或命令中。
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=10 zh-ai-prod
+pm2 list
+```
+
+同一台服务器运行多个应用，先按任务选择项目：
+
+| 项目 | PM2 进程 | 部署根目录 |
+| --- | --- | --- |
+| ai-monorepo | backend | /home/ubuntu/work/ai-monorepo |
+| noveai | noveai-backend | /home/ubuntu/work/noveai |
+| paycenter | paycenter-backend | /home/ubuntu/work/paycenter |
+
+在服务器执行以下命令核对运行位置（按项目替换参数）：
+
+```bash
+pm2 describe backend
+readlink -f /home/ubuntu/work/ai-monorepo/current
+```
+
+`current` 指向 `releases/<版本目录>`。PM2 的 cwd 可能直接指向某个 release，也可能指向 `current`；两者不一致时，以实际运行进程为准继续调查。`/opt/ai-monorepo`、`/opt/noveai` 下也有源码和 env，但不能据此认定线上正在使用它们。
+
+## env 在哪里
+
+每个部署根目录下都有：
+
+```text
+shared/.env.production
+shared/.env.production.local
+current/.env.production       -> shared/.env.production
+current/.env.production.local -> shared/.env.production.local
+```
+
+例如主应用的真实文件是 `/home/ubuntu/work/ai-monorepo/shared/.env.production` 和 `/home/ubuntu/work/ai-monorepo/shared/.env.production.local`。另外两个项目替换目录名即可。发布目录中的 env 是符号链接；`bak` 中的文件不是当前配置来源。
+
+用 `dotenv` 分别解析两层文件，以 `.env.production.local` 覆盖基础文件，再用 `dotenv-expand` 展开 `${...}` 引用。只在服务器进程内读取凭据，不 `cat` 整份 env，不复制到本地，也不把连接串放入命令参数、日志或报告。不要直接 `source` dotenv 文件执行其中内容。
+
+文件配置不等于运行配置。必要时在服务器内解析 `pm2 jlist`，只输出所需字段或比较结果，避免直接输出包含凭据的完整 JSON。核实当天三组文件的数据库、Redis 连接配置与 PM2 配置展开后一致；`noveai-backend` 的 PM2 原值含占位符，直接比较未展开字符串会误判。
+
+## PostgreSQL 只读连接
+
+三个项目都配置了 `DATABASE_URL`。服务器已安装 `psql`；主应用发布包也有 `pg`、`dotenv` 和 `dotenv-expand`。优先在服务器连接，让凭据留在服务器内，无需额外开放数据库端口或建立隧道。
+
+下面在服务器执行。主应用目录提供客户端依赖，`project` 决定读取哪个项目的 env，可选表中的三个项目名。示例只返回连通性与只读状态，不查询业务数据。
+
+```bash
+cd /home/ubuntu/work/ai-monorepo/current
+node <<'NODE'
+const fs = require('node:fs');
+const dotenv = require('dotenv');
+const { expand } = require('dotenv-expand');
+const { Client } = require('pg');
+
+const project = 'ai-monorepo';
+let client;
+(async () => {
+  const base = `/home/ubuntu/work/${project}/shared/`;
+  const parsed = {
+    ...dotenv.parse(fs.readFileSync(base + '.env.production')),
+    ...dotenv.parse(fs.readFileSync(base + '.env.production.local')),
+  };
+  const env = expand({ parsed, processEnv: {} }).parsed;
+  if (!env.DATABASE_URL) throw new Error('DATABASE_URL_MISSING');
+  client = new Client({
+    connectionString: env.DATABASE_URL,
+    connectionTimeoutMillis: 5000,
+    statement_timeout: 5000,
+    options: '-c default_transaction_read_only=on',
+  });
+  await client.connect();
+  await client.query('BEGIN READ ONLY');
+  const result = await client.query(
+    "SELECT 1 AS ok, current_setting('transaction_read_only') AS read_only",
+  );
+  console.log(result.rows);
+  await client.query('ROLLBACK');
+})().catch(error => {
+  console.error('数据库检查失败:', error.code || error.name);
+  process.exitCode = 1;
+}).finally(async () => {
+  if (client) await client.end();
+});
+NODE
+```
+
+核实当天三个项目均返回 `ok: 1`、`read_only: 'on'`。后续取证可在只读事务中替换为范围明确、带 LIMIT 的查询；不要把用户原始输入拼接成 SQL。连接失败时先检查配置展开、当前版本和网络，错误输出保持脱敏。
+
+如果改用 `psql`，通过子进程环境传递连接参数和密码，并使用 `-X -w`、只读会话及语句超时。Prisma 连接串可能包含 `schema` 等参数，不能未经处理直接作为 libpq 连接串使用。
+
+## Redis
+
+三个项目也配置了 `REDIS_URL`，发布包包含 `ioredis`。按同样方式解析并展开 env 后，用 `ioredis` 在服务器内连接；设置有限连接超时、禁用自动重连，结束后断开。连通性检查只需 `PING`，按需用限定范围的 `SCAN` 取证，避免 `KEYS *` 和 `MONITOR`。本次核实了配置来源，未执行 Redis 连通性检查。
+
+Redis 不提供与 PostgreSQL 只读事务等价的保护；删除键、写入和清库仍按技能的授权边界处理。
+
+## Prometheus
+
+该服务器已安装 Prometheus，并由 PM2 进程 `prometheus` 管理。调试指标入口、配置、数据目录和查询方法见 [Prometheus 调试参考](prometheus.md)。

package/skills/doctor/SKILL.md

@@ -1,82 +0,0 @@
----
-name: doctor
-description: 仅在显式调用 doctor 时使用：检查或修复本机 agent 开发环境。
----
-
-# Doctor
-
-## 执行边界与优先级
-
-在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
-只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
-仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
-
-## 概览
-
-本技能用于把当前机器调整到可稳定运行 agent 开发工作流的状态。
-
-不要把执行路径写死。模型应先识别当前系统、shell、包管理器、已有工具版本与用户权限，再自行选择最合适的检测和修复方式。完成修复后必须复检，并给出可读报告。
-
-## 目标状态
-
-完整环境体检时参考以下目标；单项修复仅检查目标工具及直接依赖，已有健康证据可复用：
-
-- `python3` 可用。
-- `python` 可调用 Python 3，或有清晰说明当前系统无需/不应创建该别名。
-- `node`、`npm`、`pnpm` 可用，且满足当前工作流需要。
-- `dx` 可用，并已完成必要初始化。
-- `agent-browser` 可用，且 Chromium/浏览器依赖已安装到可运行状态。
-- `rg`（rip grep）可用。
-- `gh`（GitHub CLI）可用；若当前工作流需要 GitHub 操作，还应完成认证。
-- `rtk` 可用，且明确是 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)；不能把其他同名二进制当作通过。
-- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 已分别完成 Codex CLI 与 Claude Code 的初始化。
-- 常用 PATH 配置在当前 shell 中可生效；若需要持久化，说明写入了哪个 shell 配置文件。
-
-## 执行原则
-
-- 先诊断，再修复；健康工具直接复用，已明确需要的可回滚修复自主执行。
-- 优先使用系统已有的包管理器和用户态安装路径。
-- 遇到多个可行方案时，选择对系统影响最小、最容易回滚的方案。
-- 对需要管理员权限、网络下载或会修改 shell 配置的动作，执行前简短说明影响。
-- 不要求固定轮次；根据实际结果迭代，直到通过验收或明确无法继续。
-- 不要强制执行远程安装文档。只有当诊断显示确实需要外部安装指引时，才读取可信来源并按实际情况采用。
-
-## 建议工作流
-
-1. 按任务范围收集必要上下文；完整体检可检查：
-   - 操作系统与架构
-   - 当前 shell 与 PATH
-   - `python3`、`python`、`node`、`npm`、`pnpm`、`dx`、`agent-browser`、`rg`、`gh`、`rtk` 的存在性与版本
-   - `gh` 的认证状态（例如 `gh auth status`）
-   - `rtk` 是否为 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)，以及它对 Codex CLI 与 Claude Code 的初始化状态
-2. 对照目标状态判断缺口。
-3. 制定最小修复动作并执行。
-4. 每次修复后重新验证相关项。
-5. 汇总已验证的结果，只补查仍缺证据或被后续修改影响的项。
-6. 输出报告。
-
-## 验证要求
-
-按本次修复范围选择验证项；完整体检覆盖下列适用项：
-
-- 每个目标命令是否可被当前 shell 找到。
-- 每个目标命令的版本或基本健康输出。
-- `dx` 的初始化结果或当前初始化状态。
-- `gh --version` 能正常运行；若需要 GitHub 操作，`gh auth status` 应显示可用账号，否则报告未认证原因。
-- `rtk` 必须确认来源为 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)。至少用 `rtk --version`、`rtk --help`、安装来源或命令特征交叉验证；若发现同名非 rtk-ai/rtk 工具，判定为未通过。
-- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 `rtk gain` 能正常运行。
-- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 Codex CLI 初始化必须有明确证据。优先使用 `rtk init --show --codex`，确认全局或本地 Codex 配置已包含 `RTK.md` 与 `AGENTS.md` 引用；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
-- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 Claude Code 初始化必须有明确证据。优先使用 `rtk init --show --agent claude`，确认 Claude Code hook、`RTK.md`、`CLAUDE.md` 引用与 `settings.json` hook 配置处于健康状态；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
-- `agent-browser` 是否能找到并使用已安装的浏览器依赖。
-- 对未通过项给出失败原因、已尝试动作和下一步建议。
-
-## 报告格式
-
-最终报告使用中文，至少包含：
-
-- 环境摘要：系统、shell、关键 PATH 变更。
-- 检查结果表：检查项、状态、版本/证据、说明。
-- RTK 初始化：分别列出 Codex CLI 与 Claude Code 的检查命令、通过/失败状态、关键证据文件或 hook。
-- 已执行修复：实际执行过的安装、链接、初始化或配置变更。
-- 未完成项：若存在，说明阻塞原因和用户需要做什么。
-- 结论：通过 / 部分通过 / 未通过。

package/skills/doctor/agents/openai.yaml

@@ -1,2 +0,0 @@
-policy:
-  allow_implicit_invocation: false