cortico 0.1.0 → 0.1.1

package/src/web/public/styles.css

@@ -135,9 +135,21 @@
   .navdot.warn { background: var(--warn); }
   .navdot.bad { background: var(--danger); }
 
-  .railfoot { padding: 10px 16px; border-top: 1px solid var(--line); font-size: 11.5px; color: var(--ink-dim); display: flex; flex-direction: column; align-items: stretch; gap: 8px; }
-  .rail-who { display: flex; align-items: center; gap: 9px; min-width: 0; }
-  .rail-name { min-width: 0; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; font-size: 13px; color: var(--ink); }
+  /* 头像、名字、那几个键在同一行:名字吃掉中间的余量,放不下就省略号。 */
+  .railfoot { padding: 10px 12px; border-top: 1px solid var(--line); font-size: 11.5px; color: var(--ink-dim); display: flex; align-items: center; gap: 8px; }
+  .rail-who { display: flex; align-items: center; gap: 9px; min-width: 0; flex: 1; }
+  .rail-name {
+    display: flex; align-items: center; gap: 5px; min-width: 0;
+    padding: 3px 6px; border: 0; border-radius: 7px; background: transparent;
+    font: 600 13px/1.35 var(--sans); color: var(--ink); cursor: pointer; text-align: left;
+  }
+  .rail-name-text { min-width: 0; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+  /* 铅笔平时不占视线,悬停/聚焦才露出来——名字可点这件事只在那时才需要说。 */
+  .rail-name-edit { display: grid; place-items: center; flex: none; opacity: 0; transition: opacity .15s ease; }
+  .rail-name-edit .icon { width: 13px; height: 13px; }
+  .rail-name:hover { background: var(--sheet-2); }
+  .rail-name:hover .rail-name-edit, .rail-name:focus-visible .rail-name-edit { opacity: .75; }
+  .rail-rename { flex: 1; min-width: 0; }
 
 
   .pagehead {
@@ -887,7 +899,7 @@
     background: color-mix(in srgb, var(--border) 84%, transparent);
   }
   .navdot { width: 6px; height: 6px; }
-  .railfoot { min-height: 62px; padding: 10px 16px 14px; border: 0; gap: 9px; }
+  .railfoot { min-height: 62px; padding: 10px 12px 14px; border: 0; gap: 8px; }
   .rail-avatar-wrap {
     display: grid;
     flex: none;
@@ -924,11 +936,12 @@
   }
   .rail-avatar-edit .icon { width: 15px; height: 15px; }
   .rail-avatar:hover .rail-avatar-edit { opacity: 1; }
-  .rail-actions { display: flex; gap: 3px; }
-  .rail-name { color: var(--foreground); }
+  .rail-actions { display: flex; flex: none; gap: 2px; }
+  .rail-name { color: var(--foreground); font: 600 13.5px/1.35 var(--sans); }
+  .rail-name:hover { background: var(--hover); }
   .rail-action {
-    width: 34px;
-    height: 34px;
+    width: 30px;
+    height: 30px;
     display: grid;
     place-items: center;
     padding: 0;

package/src/web/server.ts

@@ -441,13 +441,16 @@ export interface ConsoleSurface {
   toolSchemas?: WebAppToolSchemasDeps;
   /** 当前 session 的非破坏性前缀重载。 */
   sessionControl?: WebAppSessionControlDeps;
+  /**
+   * 可选的运行控制，未挂载时 /api/run/* 返回 503；暂停期间事件仍落库排队。
+   * shutdown 按装配层顺序停止投递、IO、托管 LLM server 并落盘，各步有时间预算并返回结果；未提供时不显示关机键，进程退出由装配层决定。
+   */
   /** 开场引导的一次性标记；缺席时控制台不给引导。 */
   onboarding?: {
     /** 删除标记；已经删过时不报错。 */
     dismiss(): void;
   };
 
-  /** 运行控制缺席时 /api/run/* 返回 503；暂停期间事件仍落库排队。关机顺序与进程退出由装配层决定。 */
   run?: {
     pause(): void;
     resume(): void;
@@ -469,7 +472,9 @@ export interface ConsoleSurface {
    * 不挂载时 /api/console/manifest 返回一份只有 framework 能力的空 manifest。
    */
   consolePageSources?: () => ConsolePageSource[];
-  /** 所有 provider 模块的本地可用性汇总；缺席时省略该状态。 */
+  /**
+   * 有没有一个可用的端点。缺省不挂:「语言模型」那一行不点灯。
+   */
   providersLamp?: (language: Language) => ConsoleLamp;
   /**
    * 浏览器端构建产物目录(含 asset-manifest.json)。缺省取仓库的 `dist/web`。
@@ -559,7 +564,9 @@ const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]']);
 
 /**
- * Host 头必须是回环名或显式绑定的地址；绑定通配地址时不校验 Host。
+ * Host 头必须是回环名或显式绑定的地址。DNS rebinding 让外站页面的 Origin 与 Host 同名,
+ * 同源闸门因此失效;这一关把请求钉在浏览器真正访问的名字上。绑到通配地址即操作员
+ * 已选择对外露面,不校验。
  */
 function isAllowedHost(hostHeader: unknown, listenHost: string): boolean {
   if (WILDCARD_HOSTS.has(listenHost)) return true;
@@ -1387,6 +1394,7 @@ export class WebApp {
       })();
     });
 
+    // 开场引导只出现一次:控制台在操作员开口或按下那颗按钮时销掉标记。
     app.post('/api/onboarding/dismiss', wrap((_req, res) => {
       const src = this.deps.onboarding;
       if (!src) { res.status(503).json({ error: '开场引导标记不可用' }); return; }

package/src/web/shared/client-panel.ts

@@ -440,7 +440,7 @@ export interface ConsolePromptInput {
   el: HTMLDivElement;
   focus(): void;
   setDisabled(disabled: boolean): void;
-  /** 设置输入框占位文本；`null` 恢复初值。 */
+  /** 盖住输入框里的灰字。`null` 回到构造时给的那一句。 */
   setPlaceholder(text: string | null): void;
 }
 

package/src/web/shared/console-protocol.ts

@@ -401,7 +401,8 @@ export interface ConsoleLampsResponse {
 }
 
 /**
- * 框架的 provider 状态灯键，与贡献页 id 使用不同的 kind。
+ * 「语言模型」那一行的灯在灯表里的键。贡献方的 page id 是 `<kind>:<id>`,
+ * kind 取 world / llm / persona,因此这个键与谁都不撞。
  */
 export const PROVIDERS_LAMP_ID = 'framework:providers';
 

package/src/worlds/minecraft/README.md

@@ -8,20 +8,70 @@
 ## 结构
 
 ```
-world.ts        World:事件面、工具面、console 自报、世界变化节流、摄像机编排
+definition.ts / config.ts / world.ts  World 定义、配置段与 World 本体(事件面、工具面、
+                 console 自报、世界变化节流、摄像机编排、PWSR 三张表)
+proxy.ts / engine-child.ts / engine-ipc.ts  主进程代理、引擎子进程与两者之间的协议
+
+连上去
 bridge.ts        mineflayer 连接/断线重连/prismarine-viewer 拉起
 mineflayer-fixes.ts  把 mineflayer 里靠客户端预测的合成与放置换成等服务端回话的版本
-world.ts         纯逻辑:世界快照 → 文本渲染、变化检测(可直接单测)
-server-config.ts server.properties 与 ops.json 读写 + 存档目录枚举(存档与玩法/权限与作弊面板)
-executor.ts      异步执行器:任务队列 + 技能实现 + 自保反射(不经 LLM)
+pathfinder-perf.ts   寻路器的代价与门开关补丁(另见 patches/ 里的 upstream 补丁)
+pathfinder-lib.d.ts  寻路器没带的类型声明
+server.ts / server-config.ts  本地服务端一键启停;server.properties 与 ops.json 读写、
+                 存档目录枚举(存档与玩法/权限与作弊面板)
+client.ts / window.ts / client-launch.ts / client-options.ts / client-skins.ts
+                 观察者客户端:拉起、等窗口、改标题、.minecraft → java 命令行、皮肤
+level-dat.ts     读存档自述(世界名、种子、生成参数)
+
+读世界
+terrain.ts       世界快照 → 文本渲染与变化检测(纯逻辑,可直接单测)
+cell-facts.ts    格的读法:锚点落到哪一格、脚下与参照面、区域扫描、方块名指纹
+geometry.ts      形状与锚点的纯几何:解析、栅格化
+item-facts.ts / entity-facts.ts / item-pick.ts / item-break.ts / piglin.ts
+                 物品与实体的事实读法
+names.ts         方块/实体/生物群系/附魔/效果的中文名表
+
+技能
 skills.ts        技能注册表:SkillCall/parseSteps/SKILL_DOC/schema 全部由一份声明生成
+executor.ts      任务队列、逐步派发(runSkill)与自保反射(不经 LLM)
+skill-context.ts 技能执行的共享契约:上下文、两种终态异常、World 交给技能的只读取用口
+skills-gather.ts   collect / find / fish / trade / probe
+skills-build.ts    build 的两种形态与蓝图施工,含上岸
+skills-dig.ts      excavate / tunnel
+skills-craft.ts    craft / eat / equip
+skills-interact.ts use 的各种形态 + ride / lead / anvil / grindstone
+skills-container.ts pickup / toss / stow / take / smelt / enchant / brew / transit
+travel.ts        寻路一次的时限与卡死判据、寻路目标归属、走不通时的试算现场
+placement.ts     贴哪一面、站哪儿放得着、放完回读确认、补光与耗材许可、工作站
+containers.ts    容器与工作站窗口:找、开得稳、槽位排序、账本登记
+inventory.ts     背包读法与放置/合成/拾取后的确认等待
+tools.ts         选具:拿哪把、够不够级、快断了没有、reserve 被迫动用的记号
+melee.ts         挑兵器、挥击与冷却、远程接管判据、附近敌对生物读数,以及 attack
+until.ts         find 与 tunnel 共用的 `until` 早停名单
+receipt.ts       回执措辞:这一步是什么、受阻现场、核验结论怎么念
+precheck.ts      前置试算:受理与出队两刻的纯读判据
+
+战斗与自保
+combat.ts / combat-context.ts / ranged.ts  被动交战、方位场、弓与投掷物
+escape.ts        脱困与回生:重生点解析、tp 回执
+body-lease.ts    身体租约仲裁:谁在什么时候占着身体
+
+蓝图
+blueprint.ts     方块状态规范化与校验
+blueprint-plan.ts 编译成施工步序、账单、回读对账
+blueprint-registry.ts  原版方块状态与放置方式的对照
+blueprint-repair.ts / blueprint-resource.ts  提交修复与版本/作业登记
+
+账本与规矩
+policy.ts        mc_policy 六格常驻规矩,五格落盘
+goal-plan.ts     PWSR 目标计划的协调与判定
 check.ts         mc_check 的断言器:受理 → 对世界求值 → 只报差异的回执(纯函数)
-client.ts        观察者客户端进程:拉起、等窗口、收干净
-window.ts        客户端那扇窗:按进程号探测有没有出来、改标题(+ client-window.ps1)
-client-launch.ts 纯计算:.minecraft 安装 → java 命令行(认 inheritsFrom)
-client-skins.ts  皮肤:选中的那张留底,启动前按账号名铺进游戏目录
-server.ts     控制台一键启停:本地 MC 服务器(java -jar server.jar)
-log.ts           World 日志转发与面板环形缓冲
+chests.ts / works.ts / explored.ts / deaths.ts  容器、成果、探索覆盖、死亡的持久账
+placed-ledger.ts 挂在 bot 实例上的小账:这一场放过、锄过、没放上的那些格
+search-observation.ts / round.ts / show.ts / readouts.ts / log.ts
+                 find 的短期观察、同轮重复查询、容器演出节拍、三份读数、日志转发
+
+console/         控制台面板两侧:服务器、存档、权限、客户端、皮肤、日志
   (Minecraft 客户端、服务端与启动器放在仓库外,不进 Git)
 ```
 
@@ -375,7 +425,7 @@ collect **只挖看得见的**：`collectVisible` 经 `canSeeBlockAt` 检查视
 
 `use.face` 接受绝对面名，省略时使用顶面。显式面同时传给 `activateBlock` 和对应的结果核验；读数中的坐标标识实际检查的格子。
 
-### 锚点几何技能族（geometry.ts + executor.ts）
+### 锚点几何技能族（geometry.ts + skills-build.ts + skills-dig.ts）
 
 **锚点几何语言**由 build/excavate/tunnel 的操作、probe 的测量及 dryRun 的试算共用：
 

package/src/worlds/minecraft/cell-facts.ts

@@ -0,0 +1,226 @@
+/**
+ * 格的读法:锚点落到哪一格、脚下与参照面、区域扫描、方块名指纹。
+ *
+ * 纯读,不改世界也不发包;`geometry.ts` 算形状,这里把形状对到活着的 bot 上。
+ */
+import type { Bot } from 'mineflayer';
+import { Vec3 } from 'vec3';
+import {
+  BLOCK_FACES, rasterize, resolveAnchors,
+  type Anchor, type BlockFace, type BoxFill, type Cell, type ShapeName,
+} from './geometry.ts';
+import { SkillBlocked } from './skill-context.ts';
+import { cropAgeAt } from './terrain.ts';
+
+/** 竖井遇到这些方块时停止下挖。 */
+export const LIQUIDS = new Set(['water', 'lava', 'bubble_column']);
+
+export const BUILD_CELL_CAP = 256;
+export const EXCAVATE_CELL_CAP = 512;
+export const PROBE_CELL_CAP = 2048;
+/** probe.where 的格数上限；只逐格读取，不生成材质构成或完整逐格报告。 */
+export const PROBE_WHERE_CELL_CAP = 8192;
+
+/** 放置的稳妥手长:服务端上限 5.1,留出身位余量 */
+export const PLACE_REACH = 4;
+
+/** 一格的六个邻格偏移;与六个面同一批向量,只是这里问的是"周围有没有",不问哪一面 */
+export const NEIGHBORS6 = Object.values(BLOCK_FACES);
+
+/** 检查目标格的六个正交相邻格是否有岩浆；不包含斜对角或隔一格的位置。 */
+export function nearLavaAt(bot: Bot, c: Cell): boolean {
+  return NEIGHBORS6.some(([dx, dy, dz]) => blockAtCell(bot, { x: c.x + dx, y: c.y + dy, z: c.z + dz })?.name === 'lava');
+}
+
+export const FACE_ZH: Record<BlockFace, string> = {
+  up: '上', down: '下', north: '北', south: '南', west: '西', east: '东',
+};
+
+/**
+ * 没指定面时挨个试的次序:先脚下那一块的上面(地上的火把、路面、垫脚全走这一条),
+ * 再头顶那一块的下面,最后四个侧面按原版 Direction 的序。
+ */
+export const FACE_TRY_ORDER: readonly BlockFace[] = ['up', 'down', 'north', 'south', 'west', 'east'];
+
+/** 「贴着 (x,y,z) 的北面」:回执里点名这一次贴的是谁的哪一面 */
+export function faceText(ref: Cell, face: BlockFace): string {
+  return `贴着 ${cellText(ref)} 的${FACE_ZH[face]}面`;
+}
+
+/** 贴某一面放时的参照方块:新方块那一格沿面的反方向退一格 */
+export function refCellOf(cell: Cell, face: BlockFace): Cell {
+  const [dx, dy, dz] = BLOCK_FACES[face];
+  return { x: cell.x - dx, y: cell.y - dy, z: cell.z - dz };
+}
+
+export function feetOf(bot: Bot): Cell {
+  const p = bot.entity.position.floored();
+  return { x: p.x, y: p.y, z: p.z };
+}
+
+/** 单个锚点 → 绝对格坐标(相对写法以执行这一刻我脚下那一格为原点) */
+export function resolveAt(bot: Bot, at: Anchor): Cell {
+  const resolved = resolveAnchors([at], feetOf(bot));
+  if (!Array.isArray(resolved)) throw new SkillBlocked(resolved.error);
+  return resolved[0];
+}
+
+export function blockAtCell(bot: Bot, c: Cell): ReturnType<Bot['blockAt']> {
+  return bot.blockAt(new Vec3(c.x, c.y, c.z));
+}
+
+export const cellKeyOf = (c: Cell): string => `${c.x},${c.y},${c.z}`;
+
+/** goto [x,z] 的落脚格:从世界顶往下第一块实心的上一格。区块未加载照实受阻,不猜 */
+export function surfaceFeetAt(bot: Bot, at: Anchor): Cell {
+  const c = resolveAt(bot, at);
+  const game = bot.game as { minY?: number; height?: number } | undefined;
+  const minY = game?.minY ?? -64;
+  const top = minY + (game?.height ?? 384);
+  for (let y = top - 1; y >= minY; y--) {
+    const b = bot.blockAt(new Vec3(c.x, y, c.z));
+    if (!b) {
+      throw new SkillBlocked(
+        `(${c.x}, ${c.z}) 那里还没加载,先走近些再用 [x,z];或者直接给 y`,
+      );
+    }
+    if (b.boundingBox === 'block') return { x: c.x, y: y + 1, z: c.z };
+  }
+  throw new SkillBlocked(`(${c.x}, ${c.z}) 整柱都没有实心方块,落不了脚`);
+}
+
+export function solidAt(bot: Bot, c: Cell): boolean {
+  const b = blockAtCell(bot, c);
+  return b != null && b.boundingBox === 'block';
+}
+
+/** 这一格贴不贴得住:实心之外还要排掉服务端必拒的参照面(见 NO_PLACE_REFERENCE) */
+export function refAt(bot: Bot, c: Cell): boolean {
+  const b = blockAtCell(bot, c);
+  return b != null && b.boundingBox === 'block' && !NO_PLACE_REFERENCE.has(b.name);
+}
+
+/** 锚点解析 + 栅格化 + 规模上限,一步到位;错误一律按受阻交回 agent */
+export function shapeCells(
+  bot: Bot,
+  shape: ShapeName | undefined,
+  anchors: readonly Anchor[],
+  fill: BoxFill | undefined,
+  cap: number,
+): Cell[] {
+  const resolved = resolveAnchors(anchors, feetOf(bot));
+  if (!Array.isArray(resolved)) throw new SkillBlocked(resolved.error);
+  // 不写形状 = 就这些格,各是各的,不连成片(build 一步放 N 处走的就是这条)
+  if (!shape) return resolved;
+  const cells = rasterize(shape, resolved, fill ?? 'solid');
+  if (!Array.isArray(cells)) throw new SkillBlocked(cells.error);
+  if (cells.length > cap) {
+    throw new SkillBlocked(`这个${SHAPE_ZH[shape]}有 ${cells.length} 格,一单上限 ${cap}`);
+  }
+  return cells;
+}
+
+export interface RegionReading {
+  /** 按方块名计数;sample 是该材质任一 Block(用于工具适配判断),nearest 是离我最近的一格 */
+  counts: Map<string, { n: number; nearest: Cell; nearestD: number; sample: NonNullable<ReturnType<Bot['blockAt']>> }>;
+  /** 真空气(air/cave_air/void_air)。作物/火把等无碰撞箱方块按名字进 counts */
+  air: Cell[];
+  unloaded: number;
+}
+
+export function readRegion(bot: Bot, cells: Cell[]): RegionReading {
+  const me = bot.entity.position;
+  const counts: RegionReading['counts'] = new Map();
+  const air: Cell[] = [];
+  let unloaded = 0;
+  for (const c of cells) {
+    const b = blockAtCell(bot, c);
+    if (!b) { unloaded++; continue; }
+    if (AIR_NAMES.has(b.name)) { air.push(c); continue; }
+    const d = Math.hypot(c.x - me.x, c.y - me.y, c.z - me.z);
+    const e = counts.get(b.name);
+    if (!e) counts.set(b.name, { n: 1, nearest: c, nearestD: d, sample: b });
+    else {
+      e.n++;
+      if (d < e.nearestD) { e.nearest = c; e.nearestD = d; }
+    }
+  }
+  return { counts, air, unloaded };
+}
+
+/** 这个体积以内逐格报「(x,y,z):方块」,再大只报聚合构成 */
+export const PROBE_CELLWISE_MAX = 27;
+export const AIR_NAMES = new Set(['air', 'cave_air', 'void_air']);
+
+/** FNV-1a;probe 差分只比对指纹,不留整片读数 */
+export function fnv32(s: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** matchBlockIds 的 id 集换成名字集,供按名读格 */
+export function blockNamesOf(bot: Bot, ids: number[]): Set<string> {
+  const wanted = new Set(ids);
+  const byName = bot.registry.blocksByName as Record<string, { id: number; name: string }>;
+  const names = new Set<string>();
+  for (const b of Object.values(byName)) if (wanted.has(b.id)) names.add(b.name);
+  return names;
+}
+
+/** (x,z) 柱在 yFrom 以上有没有实心遮盖;未加载的一律按露天算(宁可少说不说错) */
+export function skyBlocked(bot: Bot, x: number, yFrom: number, z: number): boolean {
+  const game = bot.game as { minY?: number; height?: number } | undefined;
+  const top = (game?.minY ?? -64) + (game?.height ?? 384);
+  for (let y = yFrom; y < top; y++) {
+    const b = bot.blockAt(new Vec3(x, y, z));
+    if (!b) return false;
+    if (b.boundingBox === 'block') return true;
+  }
+  return false;
+}
+
+/** 读取作物 age 前构造 Vec3；真实 Mineflayer 的 blockAt 需要坐标的 floored()。 */
+export function cropAgeOfCell(bot: Bot, c: Cell): { value: number; max: number } | null {
+  return cropAgeAt(bot, new Vec3(c.x, c.y, c.z));
+}
+
+export function chebyshev(a: Cell, b: Cell): number {
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y), Math.abs(a.z - b.z));
+}
+
+export const SHAPE_ZH: Record<ShapeName, string> = {
+  line: '直线', rect: '平面', triangle: '三角面', arc: '弧线', box: '长方体',
+};
+
+/** 格坐标进回执的样子 */
+export function cellText(c: Cell): string {
+  return `(${c.x}, ${c.y}, ${c.z})`;
+}
+
+/**
+ * 拿它当放置参照面服务端必拒的那些方块。耕地的顶面不是完整实心面,作物根本没有
+ * 碰撞箱;两者都点不成一次 use_item_on。这份集合只收原版确定性拒绝的,
+ * 悬空/树上那类「有时能成」的不进。
+ */
+export const NO_PLACE_REFERENCE = new Set([
+  'farmland',
+  'wheat', 'carrots', 'potatoes', 'beetroots', 'nether_wart',
+  'melon_stem', 'pumpkin_stem', 'attached_melon_stem', 'attached_pumpkin_stem',
+  'torchflower_crop', 'pitcher_crop',
+]);
+
+export function dimensionOf(bot: Bot): string {
+  return String(bot.game?.dimension ?? 'overworld');
+}
+
+/** 方块状态属性的原值;prismarine 不给 `getProperties` 时返回 null */
+export function blockProp(b: ReturnType<Bot['blockAt']>, key: string): string | null {
+  if (!b || typeof b.getProperties !== 'function') return null;
+  const v = b.getProperties()[key];
+  return v === undefined ? null : String(v);
+}
+

package/src/worlds/minecraft/chests.ts

@@ -290,3 +290,8 @@ export class ChestBook {
     writeFileSync(this.file, `${JSON.stringify(obj)}\n`, 'utf8');
   }
 }
+/** 箱子族在世界里的扫描名单;与账本认箱子的口径同一份(见 chests.ts CHEST_BLOCKS) */
+export const CONTAINER_FIND: readonly string[] = CHEST_BLOCKS;
+
+export const FURNACE_KINDS = new Set<string>(FURNACE_BLOCKS);
+