principles-disciple 3.2.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/dist/bundle.js +477 -471
  2. package/dist/constants/tools.d.ts +8 -1
  3. package/dist/core/trajectory-retention-trigger.d.ts +13 -0
  4. package/dist/core/trajectory.d.ts +14 -0
  5. package/dist/hooks/gate-block-helper.d.ts +17 -0
  6. package/dist/hooks/gate.d.ts +7 -2
  7. package/dist/host-runtime/openclaw-host-runtime.d.ts +1 -0
  8. package/dist/index.d.ts +5 -0
  9. package/dist/openclaw.plugin.json +1 -1
  10. package/dist/rulehost-evidence.js +29 -23
  11. package/dist/templates/langs/en/skills/pd-cli-operator/SKILL.md +16 -5
  12. package/dist/templates/langs/en/skills/pd-control/SKILL.md +7 -6
  13. package/dist/templates/langs/en/skills/pd-pain-signal/SKILL.md +141 -28
  14. package/dist/templates/langs/en/skills/pd-review/SKILL.md +15 -1
  15. package/dist/templates/langs/zh/skills/pd-cli-operator/SKILL.md +16 -5
  16. package/dist/templates/langs/zh/skills/pd-control/SKILL.md +7 -6
  17. package/dist/templates/langs/zh/skills/pd-pain-signal/SKILL.md +142 -29
  18. package/dist/templates/langs/zh/skills/pd-review/SKILL.md +15 -1
  19. package/openclaw.plugin.json +1 -1
  20. package/package.json +4 -4
  21. package/templates/langs/en/skills/pd-cli-operator/SKILL.md +16 -5
  22. package/templates/langs/en/skills/pd-control/SKILL.md +7 -6
  23. package/templates/langs/en/skills/pd-pain-signal/SKILL.md +141 -28
  24. package/templates/langs/en/skills/pd-review/SKILL.md +15 -1
  25. package/templates/langs/zh/skills/pd-cli-operator/SKILL.md +16 -5
  26. package/templates/langs/zh/skills/pd-control/SKILL.md +7 -6
  27. package/templates/langs/zh/skills/pd-pain-signal/SKILL.md +142 -29
  28. package/templates/langs/zh/skills/pd-review/SKILL.md +15 -1
@@ -1,21 +1,31 @@
1
1
  ---
2
2
  name: pd-cli-operator
3
- description: Use for read-only PD health checks, querying pains/tasks/runs/candidates/artifacts, tracing pain-to-principle evidence, or diagnosing PD CLI and Runtime issues. Do not use for pain registration, Owner governance review, or host setup/control.
3
+ description: Use for read-only PD health checks, querying pains/tasks/runs/candidates/artifacts, checking governance switches and worker liveness, tracing pain-to-principle evidence, or diagnosing PD CLI and Runtime issues. Do not use for pain registration, Owner governance review, or host setup/control.
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
+
7
9
  # PD CLI Operator
8
10
 
9
11
  Use the existing PD CLI to inspect facts and locate pipeline breaks. This skill routes operations; it does not implement a second business logic path.
10
12
 
13
+ ## Workspace
14
+
15
+ Use the authoritative workspace supplied by the current OpenClaw host/plugin context. When a command requires `--workspace`, pass the confirmed absolute path. If the workspace is unknown, report the blocker instead of guessing from the current directory or another host.
16
+
11
17
  ## Workflow
12
18
 
13
- 1. **Resolve the workspace.** Use the authoritative workspace supplied by the current OpenClaw host/plugin context. When a command requires `--workspace`, pass the confirmed absolute path. If the workspace is unknown, report the blocker instead of guessing from the current directory or another host.
19
+ 1. **Resolve the workspace.** Follow the host rule in the Workspace section above. If the workspace is unknown, report the blocker instead of guessing from the current directory or another host.
14
20
  2. **Discover actual commands.** Start with `pd --help`, then inspect the target command's `--help`. The installed CLI is authoritative.
15
21
  3. **Prefer read-only inspection.** Choose the smallest set of queries that answers the question; do not scan unrelated workspaces.
16
22
  4. **Trace each stage.** Verify pain registration, diagnostic task, run result, candidate, admission, and Owner governance separately. Never infer that the whole chain completed from one status field.
17
23
  5. **Report evidence.** Separate confirmed facts, unknowns, the blocked stage, and next steps. Distinguish command success from business success.
18
24
 
25
+ ## Host integration self-check
26
+
27
+ OpenClaw's `/pd-status` primarily reports host status such as GFI/Pain dictionary; it is not a substitute for Runtime health or tracing a specific task.
28
+
19
29
  ## Common read-only commands
20
30
 
21
31
  Confirm that the installed CLI supports a command before running it:
@@ -28,8 +38,6 @@ Confirm that the installed CLI supports a command before running it:
28
38
  - Task and run: `pd task show "<taskId>" --workspace "<workspace>" --json`, `pd run show "<runId>" --workspace "<workspace>"`
29
39
  - Candidates and artifacts: `pd candidate list --task-id "<taskId>" --workspace "<workspace>" --json`, `pd candidate show "<candidateId>" --workspace "<workspace>" --json`, `pd artifact show "<artifactId>" --workspace "<workspace>" --json`
30
40
 
31
- OpenClaw's `/pd-status` primarily reports host status such as GFI/Pain dictionary; it is not a substitute for Runtime health or tracing a specific task.
32
-
33
41
  ## Recall a principle's historical pains
34
42
 
35
43
  Use `pd pain recall` when the principle text alone is not enough: you are unsure why the principle exists, what its trigger boundary is, or whether the current situation matches the original failure. Do not call it when the principle is already clear or the task is unrelated to its history — it only adds latency.
@@ -52,12 +60,13 @@ Reading the result:
52
60
  - Task creation does not prove diagnosis completed.
53
61
  - Candidate generation does not prove admission; inspect the actual admission decision and corresponding ledger evidence.
54
62
  - Admission does not prove Owner approval or activation; opening the Console does not prove a governance decision was made.
63
+ - A registered worker is not a running worker; an installed plugin is not a loaded skill; a passing health check does not prove that a particular pain was diagnosed.
55
64
 
56
65
  ## Writes and failures
57
66
 
58
67
  This skill is read-only by default. Before any retry, recovery, repair, or other side effect, confirm user intent, command help, eligibility, and impact. Use dry-run first when supported and read back the resulting state afterward. Do not blindly retry commands that may have side effects.
59
68
 
60
- When the CLI is unavailable, preserve the actual error and distinguish missing installation, uninitialized workspace, insufficient permissions, and Runtime failure. Route host installation, initialization, disablement, or recovery to `pd-control`.
69
+ When the CLI is unavailable, preserve the actual error and distinguish missing installation, uninitialized workspace, insufficient permissions, and Runtime failure. Route host installation, initialization, disablement, or recovery to `pd-control`; candidate review to `pd-review`; and Owner feedback registration to `pd-pain-signal`.
61
70
 
62
71
  ## Never
63
72
 
@@ -66,3 +75,5 @@ When the CLI is unavailable, preserve the actual error and distinguish missing i
66
75
  - Fabricate runtime evidence or present a hypothesis as a confirmed root cause.
67
76
  - Approve, reject, or activate a principle through CLI, scripts, or another skill.
68
77
  - Treat exit code 0 as automatic proof of business success.
78
+ - Initialize a project directory or switch to another host's governance store.
79
+ - Describe worker registration or plugin presence as real execution or effective behavior.
@@ -4,15 +4,15 @@ description: Use when the Owner explicitly requests installation, initialization
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
+
7
9
  # PD Control
8
10
 
9
11
  ## Purpose
10
12
 
11
- Manage PD integration through the official installer and host management surface. This skill is a constrained router; it does not duplicate installer logic or mutate principle, candidate, task, or ledger state.
12
-
13
- ## Current OpenClaw support
13
+ Manage PD integration through the official installer and host management surface. This skill is a constrained router; it does not duplicate installer logic or mutate principle, candidate, task, or ledger state. Only perform an operation explicitly requested by the Owner.
14
14
 
15
- ### Install or initialize
15
+ ## Install or initialize
16
16
 
17
17
  Only when the Owner explicitly requests installation/initialization, use the documented non-interactive installer:
18
18
 
@@ -20,7 +20,7 @@ Only when the Owner explicitly requests installation/initialization, use the doc
20
20
 
21
21
  Check the installed version's help and prerequisites first. Do not claim success when authorization, network, or dependency requirements are missing. After installation, use `pd-cli-operator` for a read-only health check.
22
22
 
23
- ### Disable
23
+ ## Disable
24
24
 
25
25
  Only when the Owner explicitly requests disablement, run:
26
26
 
@@ -28,7 +28,7 @@ Only when the Owner explicitly requests disablement, run:
28
28
 
29
29
  This uses OpenClaw's official plugin-management route and does not delete installed files. Then inspect `openclaw plugins list --enabled --json` and confirm `principles-disciple` is no longer enabled. When a Gateway is running, the command applies the state change through that Gateway; distinguish a disabled switch from proof that every previously started task has stopped.
30
30
 
31
- ### Enable or resume
31
+ ## Enable or resume
32
32
 
33
33
  Only when the Owner explicitly requests enablement, run:
34
34
 
@@ -48,3 +48,4 @@ Distinguish installer success, host plugin discovery, actual Hook execution, and
48
48
  - Overwrite user configuration or delete business data to disable PD.
49
49
  - Approve, reject, or activate principles through CLI, scripts, or another skill.
50
50
  - Report an unverified host operation as successful.
51
+ - Describe installation, registration, or configuration presence as PD being actually enabled.
@@ -1,45 +1,158 @@
1
1
  ---
2
2
  name: pd-pain-signal
3
- description: Use when the Owner explicitly asks to record an agent behavior problem, register a pain signal, or trace whether feedback entered the diagnostic pipeline. Automatic pain detection remains the responsibility of existing hooks, host entrypoints, and Runtime.
3
+ description: Register an anchored behavior deviation (Pain) from the current OpenClaw conversation. Use when the Owner explicitly asks to record a concrete behavior problem and you can name the anchor. The anchored write goes through the PD MCP tool pd_submit_pain; never submit in the background and never invent an anchor.
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
- # PD Pain Signal
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
8
 
9
- ## Purpose
9
+ # PD Pain Signal (OpenClaw)
10
10
 
11
- Send the Owner's real behavior feedback through the existing PD pain-registration and diagnosis pipeline while preserving the original statement, source, and available session evidence. This skill does not reimplement detection, deduplication, admission, or diagnosis.
11
+ Pain = a concrete behavior deviation relative to a named anchor. Three elements must hold together:
12
12
 
13
- ## Steps
13
+ 1. **Anchor** — an Owner expectation, an established principle, or an in-force Agent Instruction / Skill requirement.
14
+ 2. **Concrete behavior** — what you actually did or failed to do.
15
+ 3. **Significant deviation** — a describable gap against that anchor.
14
16
 
15
- 1. **Check whether it was already recorded.** The current message may already have been handled by a hook or host entrypoint. If a real receipt exists, reuse its pain/task IDs. Do not submit a duplicate. If registration is not observable, do not claim success or blindly retry.
16
- 2. **Preserve the Owner's words.** Use only a statement the Owner explicitly provided. Do not add a technical root cause, score, or tool-failure fact. Quoted text, tool output, and model paraphrases must not be presented as a new Owner submission.
17
- 3. **Use the trusted host entrypoint.**
18
- - In the OpenClaw session where the issue occurred, when the Owner explicitly requests registration, use the host command `/pd-pain <issue description>`. OpenClaw binds the authenticated current session.
19
- - Outside the session, use the CLI only with a known, validated session: `pd pain record --reason "<reason>" --workspace "<workspace>" --session "<session-id>" --json`.
20
- 4. **Do not guess session IDs.** Never scan the database, pick the "latest" session, or substitute another host's ID. If the required session identity is missing, stop that CLI path and explain why.
21
- 5. **Verify the receipt.** Report registration only when the actual receipt confirms it. Without a receipt, say registration is unconfirmed.
17
+ No proven impact, no repetition and no prior Owner correction are NOT reasons to withhold a submission. They only help the Owner decide attention priority.
22
18
 
23
- ## Evidence and success criteria
19
+ ## Entry 1 — native host entry: `/pd-pain` (Owner-initiated, not yours)
24
20
 
25
- - A real pain ID proves only that registration returned a receipt, not that diagnosis completed.
26
- - Generated candidates are not necessarily admitted.
27
- - Check the actual `admissionResults` / `candidateOutcomes` for an `admitted` decision and its non-empty `ledgerEntryIds`. A non-empty `candidateIds` alone is not success.
28
- - Report `needs_evidence`, `deferred`, and explicit admission rejection honestly. Never bypass the admission gate or fabricate trajectory evidence to increase confidence.
29
- - The Owner's statement, host trajectory, model diagnosis, admission result, Owner approval, and activation state are distinct evidence types.
21
+ The Owner runs:
30
22
 
31
- ## Failure handling
23
+ /pd-pain <description>
32
24
 
33
- - Registration failure: preserve the real error and the host-provided next action.
34
- - Duplicate risk: check existing receipts and idempotency first.
35
- - Missing or untrusted session: stop; never guess.
36
- - CLI/hook unavailable: ask `pd-cli-operator` to inspect status; route installation repair to `pd-control`.
37
- - If the Owner wants to inspect resulting candidates, use `pd-review` to open the Console; do not re-register the same feedback.
25
+ OpenClaw dispatches the plugin command with the authenticated current session and writes the signal itself. Rules:
26
+
27
+ - Do not simulate the command, do not call it on the Owner's behalf, and do not register the same message a second time.
28
+ - If you can see a real receipt, report only the identifiers and status it actually returned.
29
+ - If the Owner asks you to register a signal but did not run the command, use Entry 2 (when the tool is available) or explain why you cannot.
30
+
31
+ ## Entry 2 — anchored submission: MCP tool `pd_submit_pain`
32
+
33
+ Check your tool list first.
34
+
35
+ - If `pd_submit_pain` is available, call it with the four possible arguments below.
36
+ - If it is not in your tool list, the anchored write capability is NOT enabled in this deployment. Stop: do not call a look-alike tool, do not compose a CLI write with guessed lineage, do not claim a submission happened. Tell the Owner the capability is unavailable, and point them at Entry 1 if they still want the signal recorded.
37
+
38
+ | argument | required | contract |
39
+ |---|---|---|
40
+ | `reason` | yes | 1–2000 characters, organized as the six parts below |
41
+ | `anchorType` | yes | `owner_expectation` / `established_principle` / `agent_instruction` |
42
+ | `anchorRef` | yes | 1–300 characters, format depends on anchor type |
43
+ | `painType` | no | `principle_deviation` / `tool_failure` / `subagent_error` / `user_frustration` |
44
+
45
+ The schema is strict. `score`, `severity`, `priority`, `sessionId`, `approved`, file paths and metadata are rejected before anything is written.
46
+
47
+ ## Anchors
48
+
49
+ Pick exactly one type. `anchorRef` must let another reader find the requirement.
50
+
51
+ ### `owner_expectation`
52
+
53
+ The Owner stated it — in this conversation, in an Owner document, or in an approved decision. `anchorRef` names where, e.g. `本次对话 14:02 Owner: "..."` or `docs/xxx.md §2`.
54
+
55
+ - Never submit an Owner expectation you can only recall. If there is no citable location, ask the Owner or do not submit.
56
+
57
+ ### `established_principle`
58
+
59
+ `anchorRef` MUST be `<principleId>@<version>` (e.g. `P-42@1`). Get both from `pd principle list`; never guess or infer the version.
60
+
61
+ The server verifies existence, version and status:
62
+
63
+ - `active` or `probation` → usable as the basis of a deviation.
64
+ `probation` returns an `anchor_probation` warning: the deviation is valid, the principle is still being validated.
65
+ - `candidate`, `archived`, `deprecated` → not usable as a basis; background only.
66
+
67
+ The server checks existence/version/status only. **Scope applicability and priority conflicts are not machine-checkable here.** If you cannot establish that the principle applies to this situation, say "适用性待确认" in `reason` instead of presenting it as settled.
68
+
69
+ ### `agent_instruction`
70
+
71
+ `anchorRef` MUST be `<path>#<section>` and MUST NOT contain spaces, e.g. `AGENTS.md#verification`. It must point at a requirement in force for the current host (AGENTS.md, PRINCIPLES.md, SKILL.md, tool guide).
72
+
73
+ ### No anchor
74
+
75
+ If you cannot classify the anchor into one of the three types, do not submit. Clarify with the Owner first.
76
+
77
+ ## `reason` — six parts, in this order
78
+
79
+ 1. **Anchor** — quote or name it (principle id@version, instruction path#section, Owner statement + location).
80
+ 2. **Anchor source and citation grade** — `verbatim` / `paraphrase` / `recollection` / `inference`. Do not upgrade the grade. A `recollection` or `inference` alone is not enough: confirm the wording with the Owner first.
81
+ 3. **Observed behavior** — specific actions, order, skipped steps, overreach. Not "the quality was poor".
82
+ 4. **Deviation** — the gap against the anchor: not done / done backwards / done but bypassed.
83
+ 5. **Why worth recording** (auxiliary) — helps the Owner prioritize. It is NOT an admission condition and must never be used to reject an otherwise valid Pain.
84
+ 6. **Context** — where and when it happened, bounded.
85
+
86
+ Never hide a conflicting anchor. Never inflate the deviation to make it easier to accept. Never turn part 5 into a threshold.
87
+
88
+ ## Authorization — one submission only
89
+
90
+ Before calling the tool, state to the Owner:
91
+
92
+ 1. the anchor and where it comes from;
93
+ 2. the concrete behavior you observed;
94
+ 3. the deviation between them;
95
+ 4. optionally, why it may matter.
96
+
97
+ Then obtain the Owner's explicit consent **in the current conversation**.
98
+
99
+ - No reply, an ambiguous answer, or a bare "whatever" is NOT authorization.
100
+ - If the Owner edits the content, re-confirm the final version before submitting.
101
+ - The authorization covers this one submission only. Never reuse it for another Pain, another session, or a retry with changed content.
102
+ - Background, scheduled, hook-driven and unattended runs MUST NOT submit on their own.
103
+
104
+ ## Severity and `painType`
105
+
106
+ - Never send a score or severity. The tool has no such parameter, and the system records an omitted severity as **moderate**. You cannot self-elevate; if you think the case is severe, say so inside `reason` for the Owner to judge.
107
+ - Omit `painType` unless you can classify it with confidence. The default is `principle_deviation`.
108
+ - The default is only valid with an `established_principle` anchor: a `principle_deviation` submission without a principle reference is refused (`anchor_invalid`, "principle_deviation requires deviationAnchor{...}"). With `owner_expectation` or `agent_instruction`, pass an explicit and honest pain type (e.g. `tool_failure`); if none fits, say so to the Owner instead of guessing.
109
+ - Never backfill `user_frustration` (or any other type) to make a submission look more urgent.
110
+
111
+ ## Reading the receipt
112
+
113
+ The tool returns one JSON receipt (`pd.pain-submit-receipt.v1`):
114
+
115
+ ```
116
+ status, painId, taskId, workspaceDir, diagnosis, anchor, provenance, warnings, error, nextAction
117
+ ```
118
+
119
+ | status | meaning | what you do |
120
+ |---|---|---|
121
+ | `submitted` | the pain and its diagnosis task were written | report `painId` / `taskId`. `diagnosis.status` is `pending`: diagnosis has NOT run |
122
+ | `refused` | nothing was written (for `task_duplicate`, an equivalent task already existed) | report `error.code` + `nextAction`; do not retry blindly |
123
+ | `failed` | the write failed; this is the only status with `isError: true` | report `error.code` / `error.message` / `nextAction`; a task may or may not exist |
124
+ | `submit_unconfirmed` | the write began and its outcome is unknown (deadline or exception) | never resubmit; run `pd task show <taskId>` and reconcile first |
125
+
126
+ `refused` codes you may see: `invalid_input`, `anchor_invalid`, `anchor_unverifiable` (ledger unreadable), `anchor_not_found` (unknown id/version or empty ledger), `anchor_not_currently_valid`, `task_duplicate`, `ingress_*`.
127
+
128
+ Degraded transports:
129
+
130
+ - `minimal` — the receipt was reduced to `status / painId / taskId / workspaceDir / diagnosis`.
131
+ - `untransportable` — a plain-text statement, or an `isError: true` envelope. An unknown outcome is always reported as UNKNOWN, never as "nothing was written".
132
+
133
+ Report only the identifiers and status the receipt actually returned. Registration is not diagnosis, not candidate admission, not approval, not activation.
134
+
135
+ ## Operator recovery (post-hoc, never the Agent default)
136
+
137
+ When the Owner's turn is already over and a trusted OpenClaw session identity is available, an operator may run:
138
+
139
+ pd pain record --reason "<summary>" --host openclaw --session "<verified session-id>" --workspace "<workspace>" --json
140
+
141
+ - Every CLI record invocation MUST bind `--session`. A record without `--session` carries no trajectory evidence and will be gated by admission (`needs_evidence`).
142
+ - Never guess, scan for, or substitute a session ID, and never pick the "latest" session. If the identity is unverified, stop and say so.
143
+ - Do not present this path as the anchored contract: it carries no `anchorType` / `anchorRef`.
144
+
145
+ ## Verify downstream state
146
+
147
+ Use `pd-cli-operator` to inspect the actual task and evidence chain. If diagnosis produced candidates, verify admission using the actual `admissionResults` / `admitted` decision and the corresponding non-empty `ledgerEntryIds`; a non-empty `candidateIds` alone is not success. Report `needs_evidence` or a rejection honestly. Use `pd-review` to open the Owner Console.
38
148
 
39
149
  ## Never
40
150
 
151
+ - Submit without an explicit Owner request and consent in the current message.
152
+ - Submit from a background, scheduled, hook or unattended run.
153
+ - Invent an anchor, a principle id@version, an Instructions path, or an Owner quote.
154
+ - Send score, severity, priority, session ids or approval tokens.
155
+ - Bypass an unavailable `pd_submit_pain` with a CLI write using guessed lineage, a local switch, or a host matcher.
156
+ - Resubmit after `submit_unconfirmed` without reconciling via `pd task show <taskId>`.
41
157
  - Write `.state/.pain_flag` or call legacy `write_pain_flag`.
42
- - Fabricate the Owner's words, session ID, turn ID, or tool failure.
43
- - Re-submit an event whose registration is confirmed.
44
- - Modify the pain database, candidate ledger, or admission state directly.
45
- - Approve, activate, or edit a principle.
158
+ - Approve, activate or modify a principle.
@@ -4,20 +4,34 @@ description: Use when the Owner wants to inspect PD diagnoses, principle candida
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
+
7
9
  # PD Review
8
10
 
9
11
  ## Purpose
10
12
 
11
13
  Help the Owner inspect real evidence and reach the official PD governance interface. The skill may query, explain, and open the Console, but it cannot make the decision for the Owner.
12
14
 
15
+ ## Workspace
16
+
17
+ Use the authoritative workspace supplied by the current OpenClaw host/plugin context. When a command requires `--workspace`, pass the confirmed absolute path. If the workspace is unknown, report the blocker instead of guessing from the current directory or another host.
18
+
13
19
  ## Workflow
14
20
 
15
21
  1. Confirm the task concerns PD pain, diagnosis, candidates, or principle governance—not ordinary code review.
16
22
  2. Use `pd-cli-operator` or an existing real receipt to verify state. Distinguish the Owner's statement, host trajectory, model diagnosis, admission decision, and completed governance action.
17
- 3. Open the Console using the workspace confirmed by the current OpenClaw host: `pd console open --workspace "<workspace>"`. Never guess the workspace.
23
+ 3. Start the Console through the host method in "Open the Console" below; never guess the workspace.
18
24
  4. Report that the Console started only when the command returns real success. If it fails, preserve the error and route host-installation diagnosis to `pd-control`.
19
25
  5. Ask the Owner to inspect the evidence and personally complete approval, rejection, or another governance action in the Console.
20
26
 
27
+ ## Open the Console
28
+
29
+ Open the Console using the workspace confirmed by the current OpenClaw host:
30
+
31
+ pd console open --workspace "<workspace>"
32
+
33
+ Never guess the workspace.
34
+
21
35
  ## State boundaries
22
36
 
23
37
  - A candidate's existence does not mean it was approved.
@@ -1,21 +1,31 @@
1
1
  ---
2
2
  name: pd-cli-operator
3
- description: 当需要只读检查 PD 运行健康、查询痛苦/任务/运行/候选/工件,或追踪痛苦到原则的证据链时使用。用于 PD CLI 与 Runtime 排障;不用于登记痛苦、Owner 治理审阅或宿主管理。
3
+ description: 当需要只读检查 PD 运行健康、查询痛苦/任务/运行/候选/工件,检查治理开关与 worker 活性,或追踪痛苦到原则的证据链时使用。用于 PD CLI 与 Runtime 排障;不用于登记痛苦、Owner 治理审阅或宿主管理。
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
+
7
9
  # PD CLI Operator
8
10
 
9
11
  通过现有 PD CLI 查询事实、定位链路断点,并给出基于证据的结论。本技能只负责操作路由,不实现第二套业务逻辑。
10
12
 
13
+ ## 工作区
14
+
15
+ 使用当前 OpenClaw 宿主/插件上下文提供的权威工作区。命令要求 `--workspace` 时传入已确认的绝对路径。无法确定工作区就先报告阻塞,不要从当前目录、最近目录或其他宿主猜测。
16
+
11
17
  ## 工作流程
12
18
 
13
- 1. **确认工作区。** 使用当前 OpenClaw 宿主/插件上下文提供的权威工作区。命令要求 `--workspace` 时传入已确认的绝对路径。无法确定工作区就先报告阻塞,不要从当前目录、最近目录或其他宿主猜测。
19
+ 1. **确认工作区。** 按上文「工作区」一节的宿主规则取权威工作区。无法确定工作区就先报告阻塞,不要从当前目录、最近目录或其他宿主猜测。
14
20
  2. **发现真实命令。** 先检查 `pd --help`,再检查目标命令的 `--help`。命令名和参数以当前安装版本为准。
15
21
  3. **优先只读检查。** 按问题选择最少的查询命令,不遍历无关工作区。
16
22
  4. **逐段追踪。** 分别核实痛苦登记、诊断任务、运行结果、候选、准入和 Owner 治理结果,不由单个状态字段推断整条链路已完成。
17
23
  5. **报告证据。** 说明已确认事实、未知部分、阻塞层和下一步;区分命令成功与业务目标成功。
18
24
 
25
+ ## 宿主接入自检
26
+
27
+ OpenClaw 的 `/pd-status` 主要展示 GFI/Pain 词典等宿主状态,不应代替 Runtime 健康检查或具体任务追踪。
28
+
19
29
  ## 常用只读命令
20
30
 
21
31
  先确认当前 CLI 支持这些命令,再按需执行:
@@ -28,8 +38,6 @@ disable-model-invocation: false
28
38
  - 任务与运行:`pd task show "<taskId>" --workspace "<workspace>" --json`、`pd run show "<runId>" --workspace "<workspace>"`
29
39
  - 候选与工件:`pd candidate list --task-id "<taskId>" --workspace "<workspace>" --json`、`pd candidate show "<candidateId>" --workspace "<workspace>" --json`、`pd artifact show "<artifactId>" --workspace "<workspace>" --json`
30
40
 
31
- OpenClaw 的 `/pd-status` 主要展示 GFI/Pain 词典等宿主状态,不应代替 Runtime 健康检查或具体任务追踪。
32
-
33
41
  ## 按需召回原则的历史痛苦
34
42
 
35
43
  当原则文本本身不够用——不确定它为何存在、触发边界是什么、或当前情况是否与当初的失败相似——使用 `pd pain recall`。原则已经清楚或任务与其历史无关时不要调用,那只会增加延迟。
@@ -52,12 +60,13 @@ OpenClaw 的 `/pd-status` 主要展示 GFI/Pain 词典等宿主状态,不应
52
60
  - 任务创建不等于诊断完成。
53
61
  - 候选生成不等于通过准入;必须检查实际 admission 决策及对应账本证据。
54
62
  - 准入成功不等于 Owner 已批准或原则已激活;打开 Console 也不等于完成治理决定。
63
+ - worker 已注册不等于 worker 正在运行;插件存在不等于技能已加载;健康检查通过不等于某条痛苦已经完成诊断。
55
64
 
56
65
  ## 写操作与失败
57
66
 
58
67
  本技能默认只读。若需要重试、恢复、修复或其他有副作用的操作,先确认用户意图、命令帮助、资格条件和影响范围;支持时先 dry-run,执行后读回真实状态。不要盲目重试可能产生副作用的命令。
59
68
 
60
- CLI 不可用时,保留真实错误并区分未安装、工作区未初始化、权限不足与 Runtime 故障。需要安装、初始化、停用或恢复宿主接入时转交 `pd-control`。
69
+ CLI 不可用时,保留真实错误并区分未安装、工作区未初始化、权限不足与 Runtime 故障。需要安装、初始化、停用或恢复宿主接入时转交 `pd-control`;需要审阅候选时转交 `pd-review`;需要登记 Owner 反馈时转交 `pd-pain-signal`。
61
70
 
62
71
  ## 禁止
63
72
 
@@ -66,3 +75,5 @@ CLI 不可用时,保留真实错误并区分未安装、工作区未初始化
66
75
  - 不伪造运行证据或把推测写成已确认根因。
67
76
  - 不通过 CLI、脚本或其他技能批准、拒绝或激活原则。
68
77
  - 不将命令退出码为 0 自动等同于业务成功。
78
+ - 不初始化项目目录,不切换到其他宿主的治理库。
79
+ - 不将 worker 注册或插件存在描述为真实运行或行为生效。
@@ -4,15 +4,15 @@ description: 当 Owner 明确要求安装、初始化、停用、重新启用或
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
+
7
9
  # PD Control
8
10
 
9
11
  ## 目标
10
12
 
11
- 通过正式安装器和宿主管理机制管理 PD 接入。本技能是受限路由入口,不复制安装器逻辑,也不改变原则、候选、任务或账本状态。
12
-
13
- ## OpenClaw 当前支持方式
13
+ 通过正式安装器和宿主管理机制管理 PD 接入。本技能是受限路由入口,不复制安装器逻辑,也不改变原则、候选、任务或账本状态。只执行 Owner 明确要求的操作。
14
14
 
15
- ### 安装或重新初始化
15
+ ## 安装或初始化
16
16
 
17
17
  仅当 Owner 明确要求安装/初始化时,使用仓库公开的非交互式安装入口:
18
18
 
@@ -20,7 +20,7 @@ disable-model-invocation: false
20
20
 
21
21
  执行前检查当前安装器的帮助和前置条件;不要在缺少授权、网络或依赖条件时声称安装成功。完成后用 `pd-cli-operator` 做只读健康检查。
22
22
 
23
- ### 停用
23
+ ## 停用
24
24
 
25
25
  只有 Owner 明确要求停用时,执行:
26
26
 
@@ -28,7 +28,7 @@ disable-model-invocation: false
28
28
 
29
29
  该命令通过 OpenClaw 正式插件管理入口更改启用状态,不会删除已安装文件。执行后检查 `openclaw plugins list --enabled --json`,确认 `principles-disciple` 不再处于启用列表。若 Gateway 正在运行,命令会通过 Gateway 应用状态变化;仍需区分“开关已关闭”和“此前已启动的任务已全部停止”。
30
30
 
31
- ### 启用或恢复
31
+ ## 启用或恢复
32
32
 
33
33
  只有 Owner 明确要求启用时,执行:
34
34
 
@@ -48,3 +48,4 @@ disable-model-invocation: false
48
48
  - 不覆盖用户配置,不删除业务数据来停用 PD。
49
49
  - 不通过 CLI、脚本或其他技能批准、拒绝或激活原则。
50
50
  - 不将未验证的宿主操作报告为成功。
51
+ - 不将安装、注册或配置存在描述为 PD 已实际启用。
@@ -1,45 +1,158 @@
1
1
  ---
2
2
  name: pd-pain-signal
3
- description: 当 Owner 明确要求记录智能体行为问题、登记痛苦信号,或追踪某次反馈是否进入诊断管线时使用。自动痛苦检测仍由现有 Hook、宿主入口和 Runtime 负责。
3
+ description: 在当前 OpenClaw 对话中登记一次带锚点的行为背离(Pain)。仅当 Owner 明确要求记录某个具体行为问题、且你能指明锚点时使用。锚点式写入走 PD MCP 工具 pd_submit_pain;禁止后台提交,禁止编造锚点。
4
4
  disable-model-invocation: false
5
5
  ---
6
6
 
7
- # PD Pain Signal
7
+ <!-- generated by @principles/pd-skills; edit packages/pd-skills/skills/** -->
8
8
 
9
- ## 目标
9
+ # PD Pain Signal(OpenClaw)
10
10
 
11
- 把 Owner 的真实行为反馈交给现有 PD 痛苦登记与诊断管线,并保留原始陈述、来源和可用的会话证据。本技能不重写检测、去重、准入或诊断逻辑。
11
+ Pain = 相对某个明确锚点的、具体的行为背离。三要素必须同时成立:
12
12
 
13
- ## 执行步骤
13
+ 1. **锚点** —— Owner 的明示要求、既有原则,或生效中的 Agent 指令 / Skill 要求。
14
+ 2. **具体行为** —— 你实际做了什么、漏了什么。
15
+ 3. **显著背离** —— 相对该锚点可以说清楚的差距。
14
16
 
15
- 1. **先检查是否已登记。** 当前消息可能已经由 Hook 或宿主入口处理。若有真实回执,复用 pain/task 标识,不要重复提交。无法观测是否登记时,不得声称成功,也不要盲目重复写入。
16
- 2. **保留 Owner 原话。** 只记录 Owner 明确提供的陈述;不要补写技术根因、评分或工具失败事实。引用、工具输出和模型转述不能伪装成新的 Owner 提交。
17
- 3. **使用可信的宿主入口。**
18
- - 在发生问题的 OpenClaw 会话中,若 Owner 明确要求登记,使用宿主命令 `/pd-pain <问题描述>`。该命令由 OpenClaw 绑定真实当前会话。
19
- - 在会话外使用 CLI 时,只能绑定已知且已验证的会话:`pd pain record --reason "<reason>" --workspace "<workspace>" --session "<session-id>" --json`。
20
- 4. **禁止猜测 session ID。** 不得猜测身份、扫描数据库、选择“最新”会话或用其他宿主的 ID 冒充当前会话。缺少必要会话标识时停止该 CLI 路径并说明原因。
21
- 5. **核验回执。** 只有实际回执证明登记成功,才能报告已登记;没有回执只能说尚未确认。
17
+ 没有证明影响、没有重复发生、Owner 之前没纠正过,都**不是**不提交的理由,只影响 Owner 的注意力排序。
22
18
 
23
- ## 证据与成功标准
19
+ ## 入口 1 —— 原生宿主入口:`/pd-pain`(Owner 发起,不是你的入口)
24
20
 
25
- - 有真实 pain ID 只代表登记有回执,不代表诊断完成。
26
- - 诊断产生候选,不代表候选通过准入。
27
- - 必须查看 `admissionResults` / `candidateOutcomes` 中的实际 `admitted` 决策及对应的非空 `ledgerEntryIds`;不能只凭 `candidateIds` 非空宣布成功。
28
- - `needs_evidence`、`deferred` 或明确的准入拒绝必须如实报告。不要绕过准入门,也不要为提高置信度而伪造轨迹。
29
- - 原始 Owner 陈述、宿主轨迹、模型诊断、准入结果、Owner 审批和激活状态是不同类型的证据,不能混为一谈。
21
+ Owner 在出问题的 OpenClaw 会话里直接发:
30
22
 
31
- ## 失败处理
23
+ /pd-pain <描述>
32
24
 
33
- - 登记失败:保留真实错误和宿主提供的下一步操作。
34
- - 重复登记风险:先核对已有回执与幂等结果。
35
- - 会话不存在或身份不可信:停止,不得猜测。
36
- - CLI/Hook 不可用:转交 `pd-cli-operator` 检查状态;需要修复安装时转交 `pd-control`。
37
- - Owner 要求查看后续候选:使用 `pd-review` 打开 Console;不要重新登记同一反馈。
25
+ OpenClaw 会把插件命令派发到当前已认证的会话,由插件自己完成写入。规则:
26
+
27
+ - 不要模拟该命令,不要替 Owner 调用,也不要把同一条消息再登记一次。
28
+ - 如果你能看到真实回执,只报告它实际返回的标识与状态。
29
+ - 如果 Owner 让你登记但并没有发这个命令,用入口 2(工具可用时),或者说明你为什么做不到。
30
+
31
+ ## 入口 2 —— 锚点式提交:MCP 工具 `pd_submit_pain`
32
+
33
+ 先看你的工具列表。
34
+
35
+ - 如果 `pd_submit_pain` 可用,用下表的四个参数调用。
36
+ - 如果工具列表里没有它,说明这套部署**没有开启**锚点式写入能力。此时停下:不要调用相似工具、不要用猜出来的 lineage 拼一条 CLI 写入、不要声称已经提交。如实告诉 Owner 该能力不可用;若仍要登记,指向入口 1。
37
+
38
+ | 参数 | 必填 | 合同 |
39
+ |---|---|---|
40
+ | `reason` | 是 | 1–2000 字符,按下面的六部分组织 |
41
+ | `anchorType` | 是 | `owner_expectation` / `established_principle` / `agent_instruction` |
42
+ | `anchorRef` | 是 | 1–300 字符,格式取决于锚点类型 |
43
+ | `painType` | 否 | `principle_deviation` / `tool_failure` / `subagent_error` / `user_frustration` |
44
+
45
+ schema 是严格的。`score`、`severity`、`priority`、`sessionId`、`approved`、文件路径与元数据都会在写入前被拒绝。
46
+
47
+ ## 锚点
48
+
49
+ 只能选一类。`anchorRef` 必须能让别人找到这条要求。
50
+
51
+ ### `owner_expectation`(Owner 明示要求)
52
+
53
+ Owner 说过 —— 本次对话、Owner 文档或已批准的决定。`anchorRef` 写明出处,例如 `本次对话 14:02 Owner: "..."` 或 `docs/xxx.md §2`。
54
+
55
+ - 只凭记忆的 Owner 要求不得提交。没有可引用的位置就先向 Owner 确认,或者不提交。
56
+
57
+ ### `established_principle`(既有原则)
58
+
59
+ `anchorRef` 必须是 `<principleId>@<version>`(例如 `P-42@1`)。两者都从 `pd principle list` 取,禁止猜测或推断版本号。
60
+
61
+ 服务端会校验存在性、版本与状态:
62
+
63
+ - `active` 或 `probation` → 可作为背离依据。
64
+ `probation` 会返回 `anchor_probation` 警告:背离成立,但该原则仍在验证期。
65
+ - `candidate`、`archived`、`deprecated` → 不能作为违规依据,只能作背景。
66
+
67
+ 服务端只校验存在性 / 版本 / 状态。**适用范围与优先级冲突无法在此机器判定。** 如果你无法确认该原则适用于当前场景,在 `reason` 里写"适用性待确认",不要写成已定论。
68
+
69
+ ### `agent_instruction`(生效中的 Agent 指令)
70
+
71
+ `anchorRef` 必须是 `<path>#<section>` 且**不含空格**,例如 `AGENTS.md#verification`。它必须指向当前宿主生效的要求(AGENTS.md、PRINCIPLES.md、SKILL.md、工具说明)。
72
+
73
+ ### 没有锚点
74
+
75
+ 如果你无法把锚点归入以上三类,不要提交。先向 Owner 澄清。
76
+
77
+ ## `reason` —— 六部分,按顺序
78
+
79
+ 1. **锚点** —— 引用或指明(原则 id@version、指令 path#section、Owner 原话 + 出处)。
80
+ 2. **锚点来源与引用等级** —— `verbatim` / `paraphrase` / `recollection` / `inference`。不得抬高等级。仅有 `recollection` 或 `inference` 时不够:先与 Owner 确认原话。
81
+ 3. **观察到的行为** —— 具体动作、顺序、跳过的步骤、越界之处。不要写"质量不好"。
82
+ 4. **背离** —— 相对锚点的差距:没做 / 做反了 / 做了但绕过了。
83
+ 5. **为何值得记录**(辅助)—— 帮 Owner 排优先级。它**不是**受理条件,绝不能用它否决一条本来有效的 Pain。
84
+ 6. **上下文** —— 何时、何地发生,范围要克制。
85
+
86
+ 不得隐瞒冲突的锚点。不得为了让提交更容易被接受而夸大背离。不得把第 5 部分变成门槛。
87
+
88
+ ## 授权 —— 仅本次
89
+
90
+ 调用工具前,先向 Owner 说明:
91
+
92
+ 1. 锚点是什么、出自哪里;
93
+ 2. 你观察到的具体行为;
94
+ 3. 两者之间的背离;
95
+ 4. 可选:为什么可能重要。
96
+
97
+ 然后在**当前对话**取得 Owner 的明确同意。
98
+
99
+ - 没有回复、回答含糊、或一句"随便"都**不是**授权。
100
+ - Owner 修改了内容,就按最终版本重新确认后再提交。
101
+ - 授权只覆盖这一次提交。不得复用于另一条 Pain、另一个会话,或内容已变化的"重试"。
102
+ - 后台、定时、hook 驱动、无人值守的运行**不得**自行提交。
103
+
104
+ ## 严重度与 `painType`
105
+
106
+ - 不要传分数或严重度。工具没有这个参数,系统会把省略的严重度记为**中等**。你不能自提;如果你认为很严重,就写进 `reason` 让 Owner 判断。
107
+ - 除非你确有把握,否则省略 `painType`。默认是 `principle_deviation`。
108
+ - 默认值只对 `established_principle` 锚点成立:没有原则引用的 `principle_deviation` 会被拒绝(`anchor_invalid`,"principle_deviation requires deviationAnchor{...}")。锚点是 `owner_expectation` / `agent_instruction` 时必须显式给出如实匹配的类型(如 `tool_failure`);没有合适的类型就向 Owner 说明,不要硬填。
109
+ - 不得为了看起来更紧急而回填 `user_frustration`(或任何其它类型)。
110
+
111
+ ## 阅读回执
112
+
113
+ 工具返回一份 JSON 回执(`pd.pain-submit-receipt.v1`):
114
+
115
+ ```
116
+ status, painId, taskId, workspaceDir, diagnosis, anchor, provenance, warnings, error, nextAction
117
+ ```
118
+
119
+ | status | 含义 | 你该做什么 |
120
+ |---|---|---|
121
+ | `submitted` | Pain 与诊断任务已写入 | 报告 `painId` / `taskId`。`diagnosis.status` 是 `pending`:诊断**尚未**运行 |
122
+ | `refused` | 没有写入(`task_duplicate` 时表示已存在等价任务) | 报告 `error.code` + `nextAction`;不要盲目重试 |
123
+ | `failed` | 写入失败,唯一带 `isError: true` 的状态 | 报告 `error.code` / `error.message` / `nextAction`;任务可能存在也可能不存在 |
124
+ | `submit_unconfirmed` | 写入已开始但结果未知(超时或异常) | 不要重提;先 `pd task show <taskId>` 对账 |
125
+
126
+ 可能见到的 `refused` 代码:`invalid_input`、`anchor_invalid`、`anchor_unverifiable`(账本不可读)、`anchor_not_found`(未知 id/版本或空账本)、`anchor_not_currently_valid`、`task_duplicate`、`ingress_*`。
127
+
128
+ 降级传输:
129
+
130
+ - `minimal` —— 回执缩减为 `status / painId / taskId / workspaceDir / diagnosis`。
131
+ - `untransportable` —— 纯文本陈述,或 `isError: true` 信封。结果未知时一律报告 UNKNOWN,绝不说成"没有写入"。
132
+
133
+ 只报告回执实际返回的标识与状态。登记不等于诊断,不等于候选受理,不等于批准,不等于激活。
134
+
135
+ ## 操作员补救路径(事后,绝不是 Agent 的默认动作)
136
+
137
+ 当 Owner 那一轮已经结束、且存在可信的 OpenClaw 会话身份时,操作员可以运行:
138
+
139
+ pd pain record --reason "<摘要>" --host openclaw --session "<已核实的 session-id>" --workspace "<工作区>" --json
140
+
141
+ - 每一次 CLI 记录调用都必须绑定 `--session`。不带 `--session` 的记录没有轨迹证据,会被准入拦截(`needs_evidence`)。
142
+ - 禁止猜测、扫描或替换 session id,禁止取"最新"的会话。身份未核实就停下来说明。
143
+ - 不要把这条路径说成锚点合同:它没有 `anchorType` / `anchorRef`。
144
+
145
+ ## 核验下游状态
146
+
147
+ 用 `pd-cli-operator` 查看实际任务与证据链。若诊断产出了候选,必须用真实的 `admissionResults` / `admitted` 决策与对应非空 `ledgerEntryIds` 核验;仅有非空 `candidateIds` 不算成功。`needs_evidence` 或拒绝都要如实报告。用 `pd-review` 打开 Owner Console。
38
148
 
39
149
  ## 禁止
40
150
 
41
- - 不写 `.state/.pain_flag`,不调用 legacy `write_pain_flag`。
42
- - 不伪造 Owner 原话、session ID、turn ID 或工具失败。
43
- - 不重复提交已确认登记的事件。
44
- - 不直接修改痛苦数据库、候选账本或准入状态。
45
- - 不批准、激活或修改原则。
151
+ - 未经当前消息里 Owner 的明确要求与同意就提交。
152
+ - 后台、定时、hook 或无人值守运行中提交。
153
+ - 编造锚点、原则 id@version、指令路径或 Owner 原话。
154
+ - 传分数、严重度、优先级、session id 或批准令牌。
155
+ - 在 `pd_submit_pain` 不可用时,用猜出来的 lineage、本地开关或宿主匹配器绕过写 CLI。
156
+ - `submit_unconfirmed` 之后不经 `pd task show <taskId>` 对账就重提。
157
+ - 写 `.state/.pain_flag` 或调用旧的 `write_pain_flag`。
158
+ - 批准、激活或修改原则。