d-robotics d671f174fe feat(v3): P0 全落地 — T01-T05b 安全骨架 + 命门根治
P0 六项任务全部完成,1044 单测全绿,tsc 0 错。

- T01 真 createAgentSession boot 离线验证(e2e-runtime + e2e-smoke 71 测试)
- T02 safety-gate 正则与 hex 归一联动,堵 devmem 十进制砖板漏洞;devmem-via-bash 硬门
- T03 reg-tool.ts:datasheet 地址校验寄存器工具,prepareArguments 接 hex 归一;barrel 22 工厂
- T04 src/core/tool-pipeline.ts:五段流水线 + 单调 guard 不变量;safety-gate 委托 decide();flash finalizeFlashContent
- T05a sandbox-policy.ts:fail-closed unusable→exitCode126 不 spawn;board-link 包 argv
- T05b native/landlock-run/landlock-run.c:C11 raw-landlock self-restrict-then-exec + Makefile + README;probeViaBinary 接线

测试方法:等价类/边界值/决策表/状态转换/变异/对抗/元蜕变(TDD test-first)。
文档:架构设计文档_v3.md 进度表 + Docs/postmortem/0001-e2e-smoke.md。

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-14 12:12:24 +08:00

295 lines
9.7 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* @module reg-tool
*
* 寄存器读写专用工具(T03)—— 安全门的" sanctioned path"。
*
* 治命门二残余 + safety-gate devmem-via-bash 兜底的配套:
* - safety-gate 现在一律 block 裸 `devmem` 走 bash(无论 hex/十进制/64 位)。
* - 本工具是唯一合法的寄存器访问路径:参数经 `makeHexNormalizingPrepareArguments`
* 归一(glm-5.2 十进制→hex),地址在 datasheet 已知寄存器表内校验通过才放行。
*
* 三件事(纯逻辑可单测,零 pi 运行时依赖):
* ① KNOWN_REGISTERS —— RDK X5 SoC 起始寄存器表(datasheet-rag 后续扩展)
* ② validateRegisterAddress —— 地址在表内 + 可写性校验(fail-closed:未知即拒)
* ③ planRegOp —— 构造 read/write 计划(带 datasheetRef 可追溯)
*
* 装配层(工厂体内):动态 import defineTool/Type 注册 `reg` 工具,
* prepareArguments 接 hex 归一。见架构设计文档_v3.md §6.1 T03。
*/
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { makeHexNormalizingPrepareArguments } from "./glm-provider.js";
// ============================================================================
// 已知寄存器表(datasheet 起始集,可被 datasheet-rag 扩展)
// ============================================================================
/** 寄存器可写性。read-only 寄存器拒绝 write(fail-closed,防误写状态寄存器)。 */
export type RegisterAccess = "ro" | "rw" | "wo";
/** datasheet 已知寄存器描述。地址 key 一律 0x 小写形式,便于查表。 */
export interface KnownRegister {
/** 寄存器地址,0x 小写形式(如 "0x40020000")。 */
address: string;
/** 寄存器名(datasheet 助记符)。 */
name: string;
/** 所属模块(GPIO/I2C/UART/CAN...)。 */
module: string;
/** 可写性。 */
access: RegisterAccess;
/** 可选:datasheet 章节引用(追溯用)。 */
datasheetRef?: string;
}
/**
* RDK X5 SoC 起始已知寄存器表(示例子集,真实用例由 datasheet-rag 扩展)。
*
* 地址以 0x 小写形式存储为 key,查表 O(1)。写未知地址一律 fail-closed 拒绝。
*/
export const KNOWN_REGISTERS: Readonly<Record<string, KnownRegister>> = Object.freeze({
"0x40020000": Object.freeze({
address: "0x40020000",
name: "GPIO_CTRL",
module: "GPIO",
access: "rw",
datasheetRef: "RDK-X5 TRM §12.4",
}),
"0x40020004": Object.freeze({
address: "0x40020004",
name: "GPIO_OE",
module: "GPIO",
access: "rw",
datasheetRef: "RDK-X5 TRM §12.5",
}),
"0x40020008": Object.freeze({
address: "0x40020008",
name: "GPIO_DATA",
module: "GPIO",
access: "rw",
}),
"0x4002000c": Object.freeze({
address: "0x4002000c",
name: "GPIO_INTSTATUS",
module: "GPIO",
access: "ro",
}),
"0x50000000": Object.freeze({
address: "0x50000000",
name: "CLK_CTRL",
module: "CLOCK",
access: "rw",
}),
});
// ============================================================================
// 地址归一 + 校验
// ============================================================================
/** 把任意 hex/十进制地址串归一为 0x 小写形式(查表用)。非地址返回 null。 */
export function normalizeAddress(raw: string): string | null {
const trimmed = raw.trim().toLowerCase();
// 已是 0x 形式
if (/^0x[0-9a-f]+$/.test(trimmed)) {
return trimmed;
}
// 纯十进制 → hex(任意位数,覆盖 32/64 位;地址无 minDigits 限制)
if (/^\d+$/.test(trimmed)) {
try {
const big = BigInt(trimmed);
return "0x" + big.toString(16);
} catch {
return null;
}
}
return null;
}
export interface AddressValidation {
/** 是否通过校验(地址在已知表内 + 可写性符合)。 */
ok: boolean;
/** 命中的寄存器描述(ok=true 时)。 */
register?: KnownRegister;
/** 失败原因(ok=false 时,fail-closed 诊断)。 */
reason?: string;
}
/**
* 校验地址是否在 datasheet 已知寄存器表内 + 可写性符合操作。
*
* fail-closed:未知地址或归一失败一律拒绝(防砖板)。
*
* @param raw 地址串(hex 或十进制,glm-5.2 强转的十进制也接受)。
* @param op 读写操作(read 不查可写性;write 需 access≠"ro")。
* @returns AddressValidation。
*/
export function validateRegisterAddress(raw: string, op: "read" | "write"): AddressValidation {
const normalized = normalizeAddress(raw);
if (normalized === null) {
return { ok: false, reason: `address "${raw}" is not a valid hex/decimal register address` };
}
const register = KNOWN_REGISTERS[normalized];
if (register === undefined) {
return { ok: false, reason: `address ${normalized} not in datasheet known-register table — refuse (fail-closed)` };
}
if (op === "write" && register.access === "ro") {
return {
ok: false,
reason: `register ${register.name} (${normalized}) is read-only — write refused`,
register,
};
}
return { ok: true, register };
}
// ============================================================================
// planRegOp —— 构造读写计划
// ============================================================================
export interface RegOpPlan {
/** 归一化后的 0x 地址。 */
address: string;
/** 寄存器描述。 */
register: KnownRegister;
/** 操作。 */
op: "read" | "write";
/** 写值(op=write 时,0x 形式)。 */
value?: string;
/** datasheet 引用(追溯)。 */
datasheetRef?: string;
}
export interface RegOpResult {
/** ok=true 时为计划;ok=false 时 undefined。 */
plan?: RegOpPlan;
/** ok=false 时为原因。 */
error?: string;
ok: boolean;
}
/** reg 工具 execute 返回的统一 details 形状(ok 时带 plan/cmd,失败时带 reason)。 */
export interface RegDetails {
ok: boolean;
reason?: string;
plan?: RegOpPlan;
cmd?: string;
}
/**
* 构造寄存器读写计划:归一地址 → 校验在表内 + 可写性 → 成计划。
*
* @param args 原始参数(address/value/op/datasheetRef)。
* @returns RegOpResult(fail-closed:未知地址/只读写 → error)。
*/
export function planRegOp(args: {
address: string;
value?: string;
op: "read" | "write";
datasheetRef?: string;
}): RegOpResult {
const { address, value, op, datasheetRef } = args;
const v = validateRegisterAddress(address, op);
if (!v.ok || !v.register) {
return { ok: false, error: v.reason };
}
const plan: RegOpPlan = {
address: v.register.address,
register: v.register,
op,
datasheetRef: datasheetRef ?? v.register.datasheetRef,
};
if (op === "write") {
if (value === undefined || value.trim() === "") {
return { ok: false, error: "write op requires a value" };
}
// 归一 value 为 0x 小写
const normVal = normalizeAddress(value);
plan.value = normVal ?? value;
}
return { ok: true, plan };
}
// ============================================================================
// 扩展装配
// ============================================================================
/**
* reg 工具扩展装配。
*
* - registerTool:`reg` 工具,schema {address, op, value?, datasheetRef?},
* prepareArguments 接 hex 归一(命门二联动),execute 调 planRegOp 校验后产命令。
* - safety-gate 已 block 裸 devmem;本工具是唯一寄存器访问路径。
*/
export default async function regToolExtension(pi: ExtensionAPI): Promise<void> {
const { defineTool } = await import("@earendil-works/pi-coding-agent");
const { Type } = await import("@earendil-works/pi-ai");
const regSchema = Type.Object(
{
address: Type.String({
description: "Register address (0x hex or decimal; glm-5.2 decimal coercion is auto-normalized).",
}),
op: Type.Union([Type.Literal("read"), Type.Literal("write")], {
description: "read or write (write requires datasheet-verified address + access≠ro).",
}),
value: Type.Optional(
Type.String({ description: "Value to write (0x hex or decimal); required for op=write." }),
),
datasheetRef: Type.Optional(
Type.String({ description: "Datasheet reference for traceability." }),
),
},
{ description: "Register read/write with datasheet address verification (sanctioned devmem path)." },
);
const regTool = defineTool({
name: "reg",
label: "Register Access",
description:
"Register read/write with datasheet address verification. Refuses unknown addresses (fail-closed). " +
"Use this instead of raw `devmem` (which safety-gate blocks).",
promptSnippet: "Read/write an MMIO register with datasheet-verified address",
parameters: regSchema,
executionMode: "sequential",
prepareArguments: makeHexNormalizingPrepareArguments(),
async execute(_id, params): Promise<{
content: Array<{ type: "text"; text: string }>;
details: RegDetails;
isError?: boolean;
}> {
const p = params as { address: string; op: "read" | "write"; value?: string; datasheetRef?: string };
const result = planRegOp(p);
if (!result.ok || !result.plan) {
return {
content: [{ type: "text", text: `REG REFUSED: ${result.error}` }],
details: { ok: false, reason: result.error },
isError: true,
};
}
const plan = result.plan;
const cmd =
plan.op === "read"
? `devmem ${plan.address}`
: `devmem ${plan.address} w ${plan.value}`;
pi.appendEntry("reg:op", {
address: plan.address,
name: plan.register.name,
op: plan.op,
value: plan.value,
datasheetRef: plan.datasheetRef,
});
return {
content: [
{
type: "text",
text: `${plan.register.name} (${plan.address}, ${plan.register.module}, ${plan.register.access}) ${plan.op === "read" ? "read" : `← ${plan.value}`} — datasheet: ${plan.datasheetRef ?? "n/a"}\ncmd: ${cmd}`,
},
],
details: { ok: true, plan, cmd },
isError: false,
};
},
});
pi.registerTool(regTool);
}