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>
295 lines
9.7 KiB
TypeScript
295 lines
9.7 KiB
TypeScript
/**
|
||
* @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);
|
||
}
|