@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3789

package/dist/atomic-write.js

@@ -0,0 +1,23 @@
+/**
+ * Same-directory temp + rename atomic file replace.
+ * Shared primitive for ledger-adjacent typed pages (analyst metrics, etc.).
+ * Does not open/truncate an existing destination inode, so hard-linked twins
+ * keep prior bytes until the directory entry is swapped.
+ * Parent directory must already exist — callers that write under the package
+ * ledger home own confinement via ensureRealDirectoryTree (ADR 0038).
+ */
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export async function writeFileAtomically(destination, contents) {
+    const parent = dirname(destination);
+    const temporary = join(parent, `.atomic-write-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents);
+        await rename(temporary, destination);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/collector-handbook.js

@@ -0,0 +1,142 @@
+/**
+ * Collector bot handbook — opaque working memory under the book topology.
+ * Runtime stores and delivers UTF-8 text only; never parses free text into
+ * code state rules (parent #673 D3 / #677).
+ *
+ * Placement reuses the machine ledger home (ADR 0048) when the admitted
+ * session already sits under books/<bookKey>/ — no parallel persistence frame.
+ */
+import { readFile } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { writeFileAtomically } from "./atomic-write.js";
+import { activationBookDirectory, assertLedgerFileInsideHome, ensureRealDirectoryTree, resolveActivationLedgerHomeForPath, } from "./activation-ledger-topology.js";
+import { COLLECTOR_HANDBOOK_MAX_BYTES } from "./collector-tool-schemas.js";
+/**
+ * Derive handbook root from an admitted session/run path under
+ * `.ak-roles/books/<bookKey>/...`. Fails closed when topology is absent.
+ */
+export function resolveCollectorHandbookRoot(sessionPath) {
+    if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
+        throw new Error("通进司手册要求非空 session 路径，且位于 books/<bookKey>/");
+    }
+    // Platform path segments only — never rewrite non-separator characters (POSIX `\\` is literal).
+    const segments = sessionPath.split(sep);
+    let bookKey;
+    for (let i = 0; i + 3 < segments.length; i += 1) {
+        if (segments[i] === ".ak-roles" && segments[i + 1] === "books") {
+            const candidate = segments[i + 2];
+            // Require a following segment so bookKey is a true path component under books/.
+            if (candidate.length > 0) {
+                bookKey = candidate;
+                break;
+            }
+        }
+    }
+    if (bookKey === undefined) {
+        throw new Error(`通进司手册要求 session 位于 books/<bookKey>/；收到 ${sessionPath}`);
+    }
+    if (bookKey === "." || bookKey === "..") {
+        throw new Error(`通进司手册拒绝不安全 bookKey ${JSON.stringify(bookKey)}`);
+    }
+    const ledgerHome = resolveActivationLedgerHomeForPath(sessionPath);
+    const root = join(activationBookDirectory(ledgerHome, bookKey), "collector-handbook");
+    return { ledgerHome, bookKey, root };
+}
+/** Flat repo file name under handbook/repos/ — avoids nested owner/repo dirs. */
+function collectorHandbookRepoFileName(repositoryCanonical) {
+    if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(repositoryCanonical)) {
+        throw new Error(`通进司手册仓库文件要求规范 owner/repo，收到 ${JSON.stringify(repositoryCanonical)}`);
+    }
+    return `${repositoryCanonical.replaceAll("/", "__")}.md`;
+}
+export function createCollectorHandbookStore(input) {
+    const generalPath = join(input.handbookRoot, "general.md");
+    const repoDir = join(input.handbookRoot, "repos");
+    const repoPath = join(repoDir, collectorHandbookRepoFileName(input.repositoryCanonical));
+    /**
+     * ADR 0038: confine at the real read seam. Parent dirs must be physical under
+     * ledger home; the leaf must not be a pre-existing symlink (even in-home).
+     */
+    /** Sole UTF-8 budget seam — write and read share COLLECTOR_HANDBOOK_MAX_BYTES. */
+    const assertHandbookBudget = (body, label) => {
+        const byteLength = Buffer.byteLength(body, "utf8");
+        if (byteLength > COLLECTOR_HANDBOOK_MAX_BYTES) {
+            throw new Error(`通进司手册${label} UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节，收到 ${byteLength}`);
+        }
+        return byteLength;
+    };
+    const readOptional = async (path, parentDir) => {
+        ensureRealDirectoryTree(input.ledgerHome, parentDir);
+        assertLedgerFileInsideHome(path, input.ledgerHome);
+        try {
+            const body = await readFile(path, "utf8");
+            assertHandbookBudget(body, "正文");
+            return body;
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return undefined;
+            throw error;
+        }
+    };
+    return {
+        root: input.handbookRoot,
+        repositoryCanonical: input.repositoryCanonical,
+        async read() {
+            const bookGeneral = await readOptional(generalPath, input.handbookRoot);
+            const bookRepo = await readOptional(repoPath, repoDir);
+            if (bookGeneral !== undefined) {
+                return {
+                    general: bookGeneral,
+                    repo: bookRepo ?? "",
+                    generalSource: "book",
+                    repoSource: bookRepo === undefined ? "empty" : "book",
+                    generalPath,
+                    repoPath,
+                };
+            }
+            const seed = input.seedGeneral;
+            if (typeof seed === "string" && seed.length > 0) {
+                assertHandbookBudget(seed, "正文");
+                return {
+                    general: seed,
+                    repo: bookRepo ?? "",
+                    generalSource: "seed",
+                    repoSource: bookRepo === undefined ? "empty" : "book",
+                    generalPath,
+                    repoPath,
+                };
+            }
+            return {
+                general: "",
+                repo: bookRepo ?? "",
+                generalSource: "empty",
+                repoSource: bookRepo === undefined ? "empty" : "book",
+                generalPath,
+                repoPath,
+            };
+        },
+        async write(scope, body) {
+            // body string shape = collectorHandbookWriteArgsSchema; byte budget is business (UTF-8).
+            const byteLength = assertHandbookBudget(body, "正文");
+            ensureRealDirectoryTree(input.ledgerHome, input.handbookRoot);
+            const path = scope === "general" ? generalPath : repoPath;
+            if (scope === "repo") {
+                ensureRealDirectoryTree(input.ledgerHome, repoDir);
+            }
+            assertLedgerFileInsideHome(path, input.ledgerHome);
+            await writeFileAtomically(path, body);
+            return {
+                scope,
+                path,
+                byteLength,
+            };
+        },
+    };
+}
+function isNotFound(error) {
+    return typeof error === "object"
+        && error !== null
+        && "code" in error
+        && error.code === "ENOENT";
+}

package/dist/collector-ledger.js

@@ -1,8 +1,6 @@
-import Value from "typebox/value";
 import { applyEvidenceVersionHistory, assignWindowRelations, COLLECTOR_ELIGIBILITY_MS, measureNormalizedBytes, normalizeAuthenticatedUserEvidence, normalizeIssueCommentEvidence, normalizePullRequestEvidence, normalizePullRequestReactionEvidence, normalizeReviewCommentEvidence, normalizeReviewEvidence, sha256Text, } from "./collector-evidence.js";
 import { buildCollectorRequestBody, } from "./collector-github.js";
 import { CollectorNonOpenRequestError } from "./collector-identity.js";
-import { collectorObserveArgsSchema, collectorOutputArgsSchema, collectorReadArgsSchema, collectorRequestArgsSchema, collectorWaitArgsSchema, } from "./collector-tool-schemas.js";
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.js";
 export const COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
 export const COLLECTOR_READ_TOOL = "ak_collector_read";
@@ -10,6 +8,8 @@ export const COLLECTOR_REQUEST_TOOL = "ak_collector_request";
 export const COLLECTOR_WAIT_TOOL = "ak_collector_wait";
 /** #676 A: role-decided target bind — business tool, ledger-booked. */
 export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
+/** #677: opaque handbook write — business tool, ledger-booked. */
+export const COLLECTOR_HANDBOOK_WRITE_TOOL = "ak_collector_handbook_write";
 export { COLLECTOR_OUTPUT_TOOL };
 export const COLLECTOR_OPERATIONAL_TOOLS = [
     COLLECTOR_BIND_TARGET_TOOL,
@@ -17,6 +17,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
     COLLECTOR_READ_TOOL,
     COLLECTOR_REQUEST_TOOL,
     COLLECTOR_WAIT_TOOL,
+    COLLECTOR_HANDBOOK_WRITE_TOOL,
 ];
 /**
  * #641 chain①: observe context projects at most this many bytes of each
@@ -24,7 +25,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
  * (evidenceId + htmlUrl) and is preserved in the volume, never unconditionally
  * transcribed into model context or receipt.
  */
-export const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
+const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
 function utf8SafePrefix(text, maxBytes) {
     if (Buffer.byteLength(text, "utf8") <= maxBytes)
         return text;
@@ -41,7 +42,7 @@ function utf8SafePrefix(text, maxBytes) {
  * (collector-side; provider-visible observe details carry only this bounded
  * projection), never unconditionally transcribed into model context.
  */
-export function projectObserveContextView(modelView) {
+function projectObserveContextView(modelView) {
     return {
         ...modelView,
         evidence: modelView.evidence.map((entry) => entry.body === undefined
@@ -50,32 +51,12 @@ export function projectObserveContextView(modelView) {
     };
 }
 export const COLLECTOR_ACTIVATION_ENTRY_TYPE = "ak-collector-activation";
-export const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot";
-export const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request";
-export const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait";
+const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot";
+const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request";
+const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait";
 function isOperationalTool(name) {
     return COLLECTOR_OPERATIONAL_TOOLS.includes(name);
 }
-/** Shared Check owner for Collector tool argument shapes (schema seam, not batch law). */
-export function collectorToolArgumentsValid(name, args) {
-    // Residual envelope: reject missing/null args before schema check.
-    if (args === undefined || args === null)
-        return false;
-    switch (name) {
-        case COLLECTOR_OBSERVE_TOOL:
-            return Value.Check(collectorObserveArgsSchema, args);
-        case COLLECTOR_READ_TOOL:
-            return Value.Check(collectorReadArgsSchema, args);
-        case COLLECTOR_REQUEST_TOOL:
-            return Value.Check(collectorRequestArgsSchema, args);
-        case COLLECTOR_WAIT_TOOL:
-            return Value.Check(collectorWaitArgsSchema, args);
-        case COLLECTOR_OUTPUT_TOOL:
-            return Value.Check(collectorOutputArgsSchema, args);
-        default:
-            return false;
-    }
-}
 export function createCollectorLedger(config, options) {
     const clock = options?.clock;
     const journal = options?.journal;
@@ -135,7 +116,7 @@ export function createCollectorLedger(config, options) {
     const prIdentity = (pr) => `${pr.state}|${pr.headOid}|${pr.updatedAt ?? ""}`;
     const requireBoundPr = () => {
         if (config.prNumber === undefined) {
-            throw new Error("Collector PR target is unbound; call ak_collector_bind_target with the role-decided issue/PR or pass --pr");
+            throw new Error("通进司 PR 目标未绑定");
         }
         return config.prNumber;
     };
@@ -449,10 +430,10 @@ export function createCollectorLedger(config, options) {
                 throw new Error("通进司已产出输出候选，本局不再受理目标绑定");
             }
             if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
-                throw new Error("Collector bind target requires a positive safe-integer PR number");
+                throw new Error("通进司绑定目标要求正安全整数 PR 号");
             }
             if (config.prNumber !== undefined && config.prNumber !== prNumber) {
-                throw new Error(`Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`);
+                throw new Error(`通进司目标已绑定 PR ${config.prNumber}，不可改绑为 ${prNumber}`);
             }
             config.prNumber = prNumber;
             appendJournal("ak-collector-target-bound", {
@@ -650,9 +631,23 @@ export function createCollectorLedger(config, options) {
             if (ledger.unresolvedTransportFailure) {
                 throw latchFatal("通进司请求时存在未恢复的传输失败");
             }
-            const request = config.manifest.requests.find((item) => item.id === input.requestId);
-            if (request === undefined) {
-                throw new Error(`未知通进司 requestId "${input.requestId}"`);
+            // Sole request identity seam: trim once, then use everywhere (lookup/marker/attemptKey).
+            // Schema pattern rejects leading/trailing whitespace at host; trim still collapses
+            // direct ledger callers and any residual padding into one stable id (#677 D2).
+            if (typeof input.requestId !== "string") {
+                throw new Error("通进司 requestId 须为字符串");
+            }
+            const requestId = input.requestId.trim();
+            if (requestId.length === 0) {
+                throw new Error("通进司 requestId 须为非空（首尾空白不构成身份）");
+            }
+            const configured = config.manifest.requests.find((item) => item.id === requestId);
+            const roleBody = typeof input.body === "string" ? input.body : undefined;
+            if (configured === undefined) {
+                // #677: role-decided trigger from handbook/field activity — body required when not in manifest.
+                if (roleBody === undefined || roleBody.trim().length === 0) {
+                    throw new Error(`未知通进司 requestId "${requestId}" 且未提供 body；请提交角色判定的请求正文或使用 request-manifest`);
+                }
             }
             const snapshot = snapshots.find((item) => item.snapshotId === input.snapshotId);
             if (snapshot === undefined) {
@@ -669,10 +664,12 @@ export function createCollectorLedger(config, options) {
                 finalObservationRequired = true;
                 throw latchFatal("通进司请求不在资格截止前");
             }
+            // Caller manifest body wins when requestId is configured; otherwise role body.
+            const configuredBody = configured?.requestBody ?? roleBody;
             const { body, marker } = buildCollectorRequestBody({
-                configuredBody: request.requestBody,
+                configuredBody,
                 manifestDigest: config.manifest.digest,
-                requestId: request.id,
+                requestId,
                 headOid: snapshot.headOid,
             });
             const existingMarker = snapshot.evidenceIds.some((id) => {
@@ -683,23 +680,23 @@ export function createCollectorLedger(config, options) {
                     record.body.includes(marker);
             });
             if (existingMarker) {
-                throw new Error(`通进司在此 HEAD 已有同 marker 的已认证请求 "${input.requestId}"`);
+                throw new Error(`通进司在此 HEAD 已有同 marker 的已认证请求 "${requestId}"`);
             }
             const boundPr = requireBoundPr();
             const attemptKey = [
                 config.repository.canonical,
                 String(boundPr),
                 snapshot.headOid,
-                request.id,
+                requestId,
             ].join("|");
             if (attemptKeys.has(attemptKey)) {
-                throw new Error(`通进司进程内请求 "${request.id}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`);
+                throw new Error(`通进司进程内请求 "${requestId}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`);
             }
             const startedAt = clock.wallNow().toISOString();
             const attemptId = sha256Text(`${attemptKey}:${startedAt}`).slice(0, 16);
             const attempt = {
                 attemptId,
-                requestId: request.id,
+                requestId,
                 observedHead: snapshot.headOid,
                 snapshotId: snapshot.snapshotId,
                 marker,
@@ -741,7 +738,7 @@ export function createCollectorLedger(config, options) {
                 return {
                     status: "succeeded",
                     attemptId,
-                    requestId: request.id,
+                    requestId,
                     observedHead: snapshot.headOid,
                     marker,
                     commentEvidenceId: record.evidenceId,
@@ -755,7 +752,7 @@ export function createCollectorLedger(config, options) {
                 return {
                     status: "ambiguous_loss",
                     attemptId,
-                    requestId: request.id,
+                    requestId,
                     observedHead: snapshot.headOid,
                     marker,
                     diagnostics: result.diagnostics,
@@ -772,12 +769,7 @@ export function createCollectorLedger(config, options) {
             if (activationTime === undefined) {
                 throw latchFatal("通进司等待需要激活");
             }
-            if (!Number.isSafeInteger(input.durationMs) || input.durationMs < 1) {
-                throw new Error("通进司等待 durationMs 须为正安全整数");
-            }
-            if (input.durationMs > COLLECTOR_ELIGIBILITY_MS) {
-                throw new Error(`通进司等待 durationMs 至多为 ${COLLECTOR_ELIGIBILITY_MS}`);
-            }
+            // durationMs shape authority = collectorWaitArgsSchema (host parameters).
             if (pastCutoff(clock)) {
                 finalObservationRequired = true;
                 throw latchFatal("通进司等待不在资格截止前");

package/dist/collector-role.js

@@ -1,9 +1,10 @@
 import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "./collector-config.js";
 import { createSystemCollectorClock, } from "./collector-evidence.js";
 import { createGhApiRunner, listPullRequestNumbersByTicket, } from "./collector-github.js";
-import { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, projectEvidenceEntryView, } from "./collector-ledger.js";
+import { createCollectorHandbookStore, resolveCollectorHandbookRoot, } from "./collector-handbook.js";
+import { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, projectEvidenceEntryView, } from "./collector-ledger.js";
 import { buildCollectorReceipt, } from "./collector-receipt.js";
-import { collectorBindTargetArgsSchema, collectorObserveArgsSchema, collectorOutputArgsSchema, collectorReadArgsSchema, collectorRequestArgsSchema, collectorWaitArgsSchema, } from "./collector-tool-schemas.js";
+import { collectorBindTargetArgsSchema, collectorHandbookWriteArgsSchema, collectorObserveArgsSchema, collectorOutputArgsSchema, collectorReadArgsSchema, collectorRequestArgsSchema, collectorWaitArgsSchema, } from "./collector-tool-schemas.js";
 import { COLLECTOR_ACCEPTED_TEXT } from "./package-contracts/collector-output.js";
 import { CorrectableSubmissionError, isCorrectableExecuteError } from "./submission-correctable-error.js";
 import { CollectorUnknownEvidenceError } from "./collector-identity.js";
@@ -26,13 +27,14 @@ export class CollectorTargetBindError extends CorrectableSubmissionError {
         this.name = "CollectorTargetBindError";
     }
 }
-export { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, };
+export { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, };
 export const COLLECTOR_REQUIRED_TOOLS = [
     COLLECTOR_BIND_TARGET_TOOL,
     COLLECTOR_OBSERVE_TOOL,
     COLLECTOR_READ_TOOL,
     COLLECTOR_REQUEST_TOOL,
     COLLECTOR_WAIT_TOOL,
+    COLLECTOR_HANDBOOK_WRITE_TOOL,
     COLLECTOR_OUTPUT_TOOL,
 ];
 /** Envelope-owned transport flags (ADR 0018 / #676 E). */
@@ -64,17 +66,34 @@ const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const bindSchema = collectorBindTargetArgsSchema;
+const handbookWriteSchema = collectorHandbookWriteArgsSchema;
 const outputSchema = collectorOutputArgsSchema;
 function buildMethodContext(activation) {
     const pr = activation.ledger.config.prNumber;
-    return [
+    const handbook = activation.handbookView;
+    const lines = [
         "<collector_method>",
         `host: github.com`,
         `repository: ${activation.repository.canonical}`,
-        `prNumber: ${pr === undefined ? "unbound — call ak_collector_bind_target with the role-decided issue/PR before observe" : String(pr)}`,
+        `prNumber: ${pr === undefined ? "未绑定" : String(pr)}`,
         `requests: ${JSON.stringify(activation.manifest.requests.map((request) => ({ id: request.id })))}`,
+        `handbookGeneralSource: ${handbook.generalSource}`,
+        `handbookRepoSource: ${handbook.repoSource}`,
         "</collector_method>",
-    ].join("\n");
+    ];
+    // Opaque working memory only — no directional instructions (ADR 0073).
+    // JSON + `<` → \u003c keeps bodies from forging the delivery close tag (#677).
+    if (handbook.general.length > 0 || handbook.repo.length > 0) {
+        const payload = JSON.stringify({
+            general: handbook.general,
+            repo: handbook.repo,
+            generalSource: handbook.generalSource,
+            repoSource: handbook.repoSource,
+            repository: activation.repository.canonical,
+        }).replaceAll("<", "\\u003c");
+        lines.push("", "<collector_handbook>", payload, "</collector_handbook>");
+    }
+    return lines.join("\n");
 }
 function parsePositiveTicket(raw, label) {
     if (raw === undefined || raw === null)
@@ -83,7 +102,7 @@ function parsePositiveTicket(raw, label) {
         return raw;
     if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim()))
         return Number(raw.trim());
-    throw new CollectorTargetBindError(`ak_collector_bind_target ${label} must be a positive safe integer`);
+    throw new CollectorTargetBindError(`通进司绑定 ${label} 须为正安全整数`);
 }
 /**
  * Shared envelope installs business tools and material callback after lifecycle gates.
@@ -118,6 +137,25 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             const clock = dependencies.createClock?.() ?? createSystemCollectorClock();
             const transport = dependencies.createTransport();
             const ledger = dependencies.createLedger({ repository, prNumber, manifest }, clock, ctx);
+            // #677: handbook under admitted book topology (session path → books/<key>/collector-handbook).
+            const sessionPath = ctx.sessionManager?.getSessionFile?.()
+                ?? ctx.sessionManager?.getSessionDir?.();
+            if (typeof sessionPath !== "string" || sessionPath.length === 0) {
+                throw new Error("通进司手册要求 session 路径位于 books/<bookKey>/");
+            }
+            const placement = resolveCollectorHandbookRoot(sessionPath);
+            const seedGeneral = dependencies.loadHandbookSeed === undefined
+                ? undefined
+                : (await dependencies.loadHandbookSeed()).trim();
+            const handbook = createCollectorHandbookStore({
+                ledgerHome: placement.ledgerHome,
+                handbookRoot: placement.root,
+                repositoryCanonical: repository.canonical,
+                ...(seedGeneral === undefined || seedGeneral.length === 0
+                    ? {}
+                    : { seedGeneral }),
+            });
+            const handbookView = await handbook.read();
             return {
                 soul,
                 repository,
@@ -125,6 +163,8 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                 ledger,
                 transport,
                 clock,
+                handbook,
+                handbookView,
             };
         },
         assembleMaterials(activation, baseSystemPrompt) {
@@ -180,7 +220,7 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                         const prNumber = parsePositiveTicket(params.prNumber, "prNumber");
                         const issueNumber = parsePositiveTicket(params.issueNumber, "issueNumber");
                         if (prNumber === undefined && issueNumber === undefined) {
-                            throw new CollectorTargetBindError("ak_collector_bind_target requires role-decided prNumber and/or issueNumber");
+                            throw new CollectorTargetBindError("通进司绑定须由角色判定 prNumber 与/或 issueNumber");
                         }
                         let bound = prNumber;
                         if (issueNumber !== undefined) {
@@ -190,14 +230,14 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                                 ticketNumber: issueNumber,
                             });
                             if (associated.length === 0) {
-                                throw new CollectorTargetBindError(`no PR associated with issue #${issueNumber} in ${activation.repository.canonical}; pass an explicit --pr or a different issueNumber`);
+                                throw new CollectorTargetBindError(`${activation.repository.canonical} 的 issue #${issueNumber} 无关联 PR；请改用明确 --pr 或其他 issueNumber`);
                             }
                             if (associated.length > 1) {
-                                throw new CollectorTargetBindError(`multiple PRs associated with issue #${issueNumber}: ${associated.join(", ")}; pass an explicit prNumber or --pr`);
+                                throw new CollectorTargetBindError(`issue #${issueNumber} 关联多个 PR：${associated.join("、")}；请改用明确 prNumber 或 --pr`);
                             }
                             const fromIssue = associated[0];
                             if (prNumber !== undefined && prNumber !== fromIssue) {
-                                throw new CollectorTargetBindError(`prNumber ${prNumber} conflicts with issue #${issueNumber} association PR ${fromIssue}`);
+                                throw new CollectorTargetBindError(`prNumber ${prNumber} 与 issue #${issueNumber} 关联 PR ${fromIssue} 冲突`);
                             }
                             bound = fromIssue;
                         }
@@ -297,8 +337,8 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             pi.registerTool({
                 name: COLLECTOR_REQUEST_TOOL,
                 label: "通进司请求",
-                description: "按配置请求体与关联标记，在所引最新快照 HEAD 发一次请求。",
-                promptSnippet: "按配置发一次请求",
+                description: "在所引最新快照 HEAD 发一次请求。requestId 可取配置清单，或角色依手册/现场判定的稳定 id；后者须同时提供 body。",
+                promptSnippet: "发一次评审请求",
                 parameters: requestSchema,
                 async execute(toolCallId, params, signal, _onUpdate, ctx) {
                     const activation = getActivation();
@@ -306,7 +346,11 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                         throw new Error("通进司未激活");
                     try {
                         activation.ledger.beginOperational(COLLECTOR_REQUEST_TOOL, toolCallId);
-                        const details = await activation.ledger.request(params, activation.transport, activation.clock, signal);
+                        const details = await activation.ledger.request({
+                            requestId: params.requestId,
+                            snapshotId: params.snapshotId,
+                            ...(typeof params.body === "string" ? { body: params.body } : {}),
+                        }, activation.transport, activation.clock, signal);
                         activation.ledger.completeOperational(toolCallId);
                         return {
                             content: [{
@@ -323,6 +367,51 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                     }
                 },
             });
+            pi.registerTool({
+                name: COLLECTOR_HANDBOOK_WRITE_TOOL,
+                label: "通进司手册写入",
+                description: "写入通用手册或当前仓库差异全文（整份替换）。",
+                promptSnippet: "更新 bot 手册",
+                parameters: handbookWriteSchema,
+                async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+                    const activation = getActivation();
+                    if (activation === undefined)
+                        throw new Error("通进司未激活");
+                    try {
+                        activation.ledger.beginOperational(COLLECTOR_HANDBOOK_WRITE_TOOL, toolCallId);
+                        // scope/body shape authority = collectorHandbookWriteArgsSchema (host parameters).
+                        const details = await activation.handbook.write(params.scope, params.body);
+                        activation.handbookView = await activation.handbook.read();
+                        activation.ledger.completeOperational(toolCallId);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `手册已写入：${details.scope}`,
+                                }],
+                            details: {
+                                scope: details.scope,
+                                path: details.path,
+                                byteLength: details.byteLength,
+                                generalSource: activation.handbookView.generalSource,
+                                repoSource: activation.handbookView.repoSource,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        if (isCorrectableExecuteError(error))
+                            throw error;
+                        hostActions.failInfrastructure(error, ctx, toolCallId);
+                    }
+                    finally {
+                        try {
+                            activation.ledger.completeOperational(toolCallId);
+                        }
+                        catch {
+                            // already completed or not begun
+                        }
+                    }
+                },
+            });
             pi.registerTool({
                 name: COLLECTOR_WAIT_TOOL,
                 label: "通进司等待",

package/dist/collector-tool-schemas.js

@@ -3,9 +3,33 @@ import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.js";
 import { openToolObject } from "./open-tool-schema.js";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
+/**
+ * Stable request identity: non-empty after trim, no leading/trailing whitespace.
+ * Host schema + ledger identity seam share this contract (#677 / D2 dedup).
+ */
+export const COLLECTOR_REQUEST_ID_PATTERN = /^\S(?:.*\S)?$/;
 export const collectorRequestArgsSchema = Type.Object({
-    requestId: Type.String({ minLength: 1, description: "配置请求身份" }),
+    requestId: Type.String({
+        minLength: 1,
+        pattern: COLLECTOR_REQUEST_ID_PATTERN.source,
+        description: "请求身份（配置 id 或角色判定的稳定 id；首尾无空白）",
+    }),
     snapshotId: Type.String({ minLength: 1, description: "最新留存观察快照" }),
+    body: Type.Optional(Type.String({
+        minLength: 1,
+        description: "角色判定的请求正文；request-manifest 未收录该 requestId 时必填",
+    })),
+}, { additionalProperties: false });
+/** UTF-8 byte ceiling per handbook body — keeps next activation materials inside context budget. */
+export const COLLECTOR_HANDBOOK_MAX_BYTES = 64 * 1024;
+export const collectorHandbookWriteArgsSchema = Type.Object({
+    scope: Type.Union([
+        Type.Literal("general"),
+        Type.Literal("repo"),
+    ], { description: "general＝通用手册；repo＝当前仓库差异" }),
+    body: Type.String({
+        description: `手册全文（opaque 工作记忆；整份替换；UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节）`,
+    }),
 }, { additionalProperties: false });
 export const collectorReadArgsSchema = Type.Object({
     evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),