Pinwhy

---
name: pinwhy
description: 恢复长期任务上下文、记录关键判断/发现/进度、压缩前保存现场或跨 Agent 交接时使用；也处理用户明确要求的 pinwhy 配置、接入、启动与打开，以及明确调用的可选 threat model / 威胁建模。适合研究、审计和长任务的可选外置记忆，不因项目存在 .pinwhy 就要求普通任务启用。
---

# Pinwhy — 可选的 Agent 外置记忆

## 触发与边界

用户要求恢复上下文、保留关键判断、交接、使用 pinwhy，或明确调用附加威胁建模时使用本 Skill。仅存在 `.pinwhy/` 不是启用所有普通任务的理由。

长研究、反复试错、上下文将丢失或关联发现值得保留时，可以一句话建议启用，说明收益与记录开销。**用户同意前不安装、不初始化。** 一次性问答、纯执行任务或用户赶时间时不建议；未回应或拒绝后不重复打扰，除非用户重新提出或任务背景实质变化。

pinwhy 只提供数据，不是工作流引擎：不批准、阻断、排序或替 Agent 决定下一步。调用失败不应阻止原任务继续；lint、context、digest 和 Hook 都不是行动前置条件。

## 先选宿主与意图

涉及黑板操作时先确认项目根目录和宿主，再选择最小操作；不要把“打开”解释成“重新安装”。仅调用威胁建模时直接按需读取对应参考，默认只返回分析，不要求已有黑板或先安装接入。

| 用户意图 | 操作 |
| --- | --- |
| 已有黑板，恢复/接手/压缩后继续 | 读取 `context`，按需要补读节点；不重新 setup |
| 仅打开查看器 | 先 `status`；若对应项目在线，访问其 URL；离线再按需启动服务 |
| 首次 Claude Code 接入或明确重配 | 先读 [接入与打开](references/setup.md)，说明 setup 副作用后使用 |
| 首次 Codex 接入 | 读 [接入与打开](references/setup.md)，用 init 和 Codex Skill 安装；不默认执行 Claude setup |
| OMP、ZCode 等其他宿主接入 | 按当前宿主机制安装完整 Skill 包并展开 CLI 路径；不增加专用 CLI 分支、不安装其他宿主的 Hook |
| 明确调用 threat model / 威胁建模 | 读 [按需威胁建模](methods/threat-model.md)；理解当前问题的安全目标、信任假设与失效条件；默认只分析 |
| 已启用，只记录关键判断 | 使用下方最小命令；复杂关系见 [记录语义](references/recording.md) |

## 命令位置与项目归属

下列例子中的 `/已确认项目` 必须替换成已确认的绝对项目路径，`<目标ID>` 等尖括号占位符必须替换成命令输出中的实际 ID。每条命令都用 `--cwd` 指定项目，避免工具调用的工作目录不同而写错项目。写命令再加 `--no-init`：黑板只在用户同意后由 `init` 或 `setup` 创建；路径写错时命令报错退出，而不是在错误位置新建一块空板。

保存承载判断、限制或证据的文本前，可用 `capabilities --json` 确认 `features.rejectTruncation`。支持时为节点创建、编辑、连边和检查点加 `--no-truncate`，超限则由你自主缩写、拆分或引用证据文件，不把半条论断保存成完整记录；这不影响原任务继续。读取到 `inputTruncation` 时，明确说明写入时曾丢失文本，不将其当作完整原输入；没有该字段的旧记录也不据此断言完整。

多个参与者共用一块黑板时，每条命令还要加 `--agent <稳定名称>`，节点、关系和修改会以该身份记为作者；单人使用可省略，默认为 `agent:primary`。详见 [并行 Agent](references/parallel-agents.md)。环境变量 `PINWHY_CWD`、`PINWHY_AGENT` 仍然有效，参数优先。CLI 若报 `未知选项 --cwd`，说明它早于本 Skill：改用这两个环境变量作命令前缀，并在写入前用 `status` 确认黑板已存在。

优先用 PATH 中的 `pinwhy`。不可用时，安装后的 Skill 可用 `node "__PINWHY_CLI__"` 替换命令名，**仅限路径已展开为真实文件**。如果路径仍是双下划线包围的 CLI 占位符，说明直接加载了仓库源 Skill；不要执行占位符、不要猜安装路径。可在已确认的 pinwhy 仓库根使用 `node bin/pinwhy.js`，否则先定位实际 CLI。

## 最小操作

恢复长期现场（默认返回结构化 JSON）：

```sh
pinwhy context --budget 4000 --cwd "/已确认项目"
```

仅查看服务与接入状态：

```sh
pinwhy status --cwd "/已确认项目"
```

查找记录优先用 `search`，而不是导出列表再写临时过滤脚本；组合筛选、统计和完整列表见[查询用法](references/recording.md#查询与统计)：

```sh
pinwhy search "关键词" --json --cwd "/已确认项目"
pinwhy search --type vuln --group-by severity,status --cwd "/已确认项目"
```

使用新筛选/分组前可读取 `capabilities --json` 的 `features.searchFilters` / `features.searchGrouping`；旧版本没有这些字段时不要使用新选项。读取 JSON 的 `total` 和 `truncated`，不要把返回的明细当作全部记录。

节点 JSON 的 status/severity/confidence 未记录时为 `null`，不能解释成 open 或已确认。`features.nodeJsonDefaults` 声明此能力，具体 schema 读 `capabilities.outputs`；`receipt.result` 保留原始写入形状。需要交付记录时，按 `capabilities.exportFormats` 选择 Markdown、Mermaid 或 SARIF，见[报告导出](references/recording.md#报告导出)，不凭空补证据或位置。

关键猜测值得保留时，新建并显式进入；已知它服务于哪个目标时，用 `--to` 一并连上：

```sh
pinwhy node add hypothesis "待验证的判断" --confidence suspected --to "<目标ID>" --enter --cwd "/已确认项目" --no-init
```

需要新节点的 ID 时加 `--json`：`node add` 读 `node.id`；`edit`、`done`、`block`、`revive` 的节点字段在顶层，读 `id`。各命令的选项、示例和输出形状用 `pinwhy <命令> --help` 查看；不要解析给人看的文本。

带 `--json` 失败时退出码为 1、stdout 为空，stderr 是一行 `pinwhy.error.v1`：读 `code`，有 `suggestion` 时据此改正后重试，`batch` 错误还带 `line` 和 `column`。CLI 声明 `features.jsonErrors` 时才依赖此格式。

等待外部依赖（源码未到、等用户答复、等长时间运行的结果）时，把卡住的节点标为 `blocked`，等到后用 `revive` 恢复为 `open`；在等什么写进检查点摘要。这只是记录，不阻止任何操作，但接手者能据此分清“刚开始”和“卡住了”：

```sh
pinwhy block "<节点ID>" --cwd "/已确认项目" --no-init
pinwhy revive "<节点ID>" --cwd "/已确认项目" --no-init
```

交接、暂停或压缩前保存现场：

```sh
pinwhy checkpoint --summary "已确认内容；当前关注点；仍开放的问题" --cwd "/已确认项目" --no-init
```

空黑板且用户同时给出实质任务时，可建目标锚点；仅配环境时不凭空创建任务或结论。研究或审计的对象是某份具体代码时，在目标里写明它的版本：标题带包名@版本或短提交号，detail 写源码的实际位置。不同版本的行号不可比，换了副本要能看出来。示例中的库名、版本和路径须换成实际值：

```sh
pinwhy goal "审计 某库@1.2.3 的解析边界" --detail "源码：实际路径或仓库与提交号" --enter --cwd "/已确认项目" --no-init
```

## 写什么，不写什么

- 记录可供未来会话复核的目标变化、关键观察、判断支持/反驳/取代、主要关注点与交接现场。
- **记录时机**：判断形成、证据出现、方向改变时就写，不等结论稳定或任务收尾再集中补记。“可选”指是否启用和记多细，不表示可以延后；过程只留在上下文里，一旦压缩或中断就丢了。
- 工作中写到磁盘的日志、台账、报告草稿不是交接入口：下一个会话从黑板恢复，不会去找这些文件。需要保留的判断写成节点，文件路径放进 `--detail`。
- 长任务或分波次的并行工作，在每一波结束时写下本波的关键判断和证据，再打检查点。检查点回显会列出自上一检查点以来的节点和关系变化；全为 0 就是这段时间没有新增记录。一次要记多条相关记录时，可用 `batch` 一条命令写入（见[并行 Agent](references/parallel-agents.md#多个子-agent-同时工作)）。
- 不把每次命令、读取、成功提示或原始输出写成逻辑节点。工具活动默认不采集；显式启用后仍是独立活动层，不自动成为事实。
- 一个节点表达一个主要判断。标题只写这个判断本身，控制在约 80 字内；证据、文件位置、条件和过程放 `--detail`。标题不复述其他节点的结论（如“hy1 被反驳”）：节点之间的关系用边表达，状态用 `--status`。
- 未验证的 finding/vuln 候选用 `suspected`；已有静态核对证据可直接用 `static-confirmed`，真实复现后才用 `reproduced`，不要求依次升级。严重度、状态和可信度相互独立。
- 关系读作 “from relation to”：证据 `supports` 或 `contradicts` 论断。创建时已知新节点与已有节点的关系，可用 `--to <已有ID> --rel <关系>` 一并声明（新节点在左，不移动游标）；`--to` 可重复，用同一关系连向多个已有节点。知道一个假设、问题或发现属于哪个目标时，就在创建时 `--to <目标ID>` 连上（省略 `--rel` 即弱关系 `related-to`），交接后结论仍能沿关系回到目标。不确定关系时不连，而不是套用默认值或为消除孤立节点补边。有足够证据推翻时才将旧论断设为 `refuted`。新结论确实取代旧结论时才用 `supersedes` 和 `superseded`；反驳不等于取代。

## 按需读取参考

只打开当前操作需要的参考，不一次加载全部：

- [接入与打开](references/setup.md)：首次接入、其他宿主的通用安装、已有黑板、服务生命周期与 setup 副作用。
- [记录语义](references/recording.md)：阈值、关系方向、可信度、查询筛选与统计、完整列表、游标与检查点。
- [并行 Agent](references/parallel-agents.md)：每次显式项目/身份、Hook 继承边界、恢复与交接查询。
- [可选的记录方法](methods/INDEX.md)：审计记录、研究记录方式、威胁建模等，每个一行说明。完全可选，用不用、用哪个由你决定，不用也是正常记录；只读你选中的那一个。

## 不可改变的边界

`.pinwhy/events.jsonl` 是唯一事实源；state、context、digest、服务快照和页面都是可重建投影，不另建权威记录。

逻辑节点/边、游标/轨迹、工具活动相互独立：创建节点默认不连边、不移动游标；当前节点不是隐式父节点，时间先后和游标轨迹不构成逻辑关系。只保存明确知道的关系，不为连图而编造因果。

并行参与者必须在每条命令用 `--agent` 明确身份；不要假设一次 `export` 会跨工具调用保留。使用前按需读取并行参考。Hook 只是可选恢复辅助，不保证子 Agent 自动恢复，也不决定行动。

## 输出预期

配置后简述实际安装/重配项、项目与服务状态、可访问 URL 或手动启动命令；区分“文件已安装”和“当前宿主已加载”。

恢复后简述已确认现场、当前关注点和开放问题，标明未知，不把投影当成下一步指令。记录后只报告实际写入的节点/关系/检查点及必要 ID；没有执行或没有证据的能力、状态与复现结果不要承诺。