nx-kv 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.16.0] - 2026-11-04 占位成员可救可清 + 仓库页可读性 + 前后端分层解耦
+
+### Added
+
+- **`board rekey <from> --to <仓库>`**：把组里的**占位 key** 重绑到本机仓库——
+  改的是**关系**（`repoKeys`），仓库登记与 key 不动；组内描述（`repoNotes`）与
+  组内文档绑定（`repoDocs`）跟着 key 搬。不给 `--board` = 全组一起重绑
+  （假 key 是身份问题，只修一个组会留下另一半残局）。目标已在组里则合并。
+- **`board prune [--board] [--all] [--apply]`**：清理占位成员。默认只清**无来源**的
+  （没有远程地址 → 克隆不回来 → 永远转不了正），带 remote 的加 `--all` 才清；
+  默认预览，`--apply` 落盘。
+- **占位成员带线索**：导入布局时把对方的 `name / remote / desc / type` 记进
+  `board.repoHints`，占位从此能显示名字、能「克隆到本地」；`board export` 也不再
+  丢掉占位（以前导出的看板比屏幕上少人）。
+
+### Changed
+
+- **修掉「用本机仓库接管」的方向错误**：它原先把**本机仓库的 key** 改成占位 key
+  （`local/xxx`），真实身份被降级并随导出传播。现在改为重绑组里的 key，登记不动。
+- **仓库页可读性**：正文字号整体提一档（表格 13.5px、描述两行、路径 12px 等宽），
+  待初始化区改成「一条占位一张卡」：名字 / 来源组 / key 分层，三个出口
+  （绑定到候选仓库 / 克隆 / 移除）+ 批量清理。
+
+### Changed（架构：前后端彻底解耦）
+
+- **模块声明里不再有 `view`**。`src/modules/<x>/index.js` 曾经写着
+  `view: () => import('../../web/frontend/page/x/index.jsx')`——后端声明里出现前端文件
+  路径，前端换个目录就要改后端代码；而 `localtask` 那条 `import('./view.jsx')` 指向的
+  文件**早就不存在**（没人读它，所以坏了也没报错）。视图现在只在前端
+  `web/frontend/registry.js` 登记，后端对自己的面板一无所知。
+- **新增同构层 `src/shared/`**：`attach.js`（附件语法）、`wikilink.js`（双链）、
+  `frontmatter.js`（任务头）以前长在后端模块里，却被前端直接 import（12 处）——
+  等于浏览器包依赖后端的目录结构。现在只有这一层能同时被两端加载，且**零依赖**
+  （不许 `node:`、不许第三方包）。
+- **两个纯前端文件归位**：`localtask/board.js`（显示序 / 队列拆分，7 处前端引用）、
+  `localtask/reopen-text.js`（重开正文拼装）没有任何后端消费方，移到
+  `web/frontend/modules/board/`；顺手删掉同目录里没人引用的 `use-cloud-dir.js`。
+- **`routes` 改成平台命令**：它描述的是 `ALL_COMMANDS` 本身，只有 runtime 拿得到。
+  以前 system 模块为它 `await import('../../runtime/cli.js')`（分层倒置），现在逻辑
+  留在 `modules/system/routes.js`（纯函数，表由调用方传入），命令挂在 `cli.js` 的
+  BUILTINS 上；`bootstrap` 下发的命令表改读 `core/command-table.js` 的快照。
+- **边界写成机器检查**：`eslint.config.js` 新增 modules→web / modules→runtime /
+  shared 零依赖 / 模块内禁 react 四类规则；新增 `tests/unit/layering.test.mjs`，
+  解析真实 import 路径比对层次（`web` 只能看到 `web + shared`），并断言后端目录里
+  没有 `.jsx`、模块不再声明 `view`。
+
+## [0.15.0] - 2026-11-04 工作组两级口径（任务带归属）+ 划线评论与完成验收闭环 + 任务附件 + 队列显示序与分页
+
+### Added
+
+- **任务带工作组归属（--board / --project）**：`localtask add --project <项目>` 让任务
+  挂到某个项目上（落点目录由归属项目的登记路径推导，任务正文自动写 frontmatter：
+  `board` / `project` + 双方介绍**引用式**字段）；`--board <项目组>` 要求归属项目必须是
+  该组成员。改文案（`update --text` / `reopen`）不丢 frontmatter；正文自带 frontmatter
+  时同样认归属（fail-open：补介绍引用，落点跟到项目队列；显式给了 `--cwd` 就不挪窝）。
+  - 领到组内任务时，交付 `instruction` 封装**项目组上下文**：组定位、组介绍、本项目
+    位置、兄弟成员角色、组绑定参考文件的可读路径（`task.text` 保持原文）。
+  - CLI、HTTP、面板提交、远程清单导入同走一条 `submitTask`（tasktool/add.js）——
+    落点判定只此一份实现。
+
+- **任务附件**：`localtask attach` 给任务追加附件（--path 上传本机文件，或 --fileId
+  追加已上传附件，以 markdown 嵌入正文末尾，与云端 todo 同构）；`localtask attachments`
+  列出某条任务引用的附件与本地是否已有。`get` / `wait` / `show` 的交付自带附件清单与
+  本地绝对路径（自动下载跟随本机设置；标注/同步 fail-open，零附件时载荷不变）。
+  面板编辑器贴图即嵌附件（图床优先，图床不可达时退回本地旧路）。
+
+- **划线评论 → 直接提交成任务**：MD 工作台划选正文 → 「评论」→ 提问**直接提交**成
+  新任务（不再先开编辑页），并**整块继承原任务的 frontmatter**——原任务属于某工作组，
+  评论出的新任务也归该组，组面板「本组任务」里能看见。
+
+- **完成任务的验收闭环**：任务完成后给出 agent 的完成总结（ack）+ 验收条——
+  **通行**（验收通过）/ **重做**（评论模式下带反馈重开，反馈加粗进正文）/
+  **提详细问题**（划线评论生成新任务）。重开时正文自动追加**上一轮完成总结**与
+  **验收反馈**两段（`modules/localtask/reopen-text.js` 唯一实现：任务页评论框与
+  列表页行内重做共用；同一份总结不追加两遍）。
+
+- **队列显示序与分页**：显示序改「**未完成（待领取）优先**」——队列数组是追加序，
+  新任务会被历史埋底；显示序与队列序分开（`sortTasksForDisplay`，桶内待领取仍按
+  队列原序）。侧栏任务子行不再硬截断 12 条（静默丢弃第 13 条起），改**分页**
+  （12 条/页）；目录任务表同样分页（20 条/页）+「N 待领取 · M 个任务」计数。
+
+- **项目组「添加成员」就地选择器**：组面板里就地弹窗——搜索框 + 「项目组」「项目」
+  两段列表；项目行加入/移出本组（行尾标出它还在哪些组），项目组行「并入 N」把该组
+  成员一并纳入（归属是复制不是移动）；不再跳仓库管理页，去掉说明性段落。
+  仓库页「成员管理 / 导入仓库」复用同一组件。
+
+- **dev-nxkv 项目级 skill**（`.claude/skills/dev-nxkv/`）：改本仓库代码的施工单——
+  分层边界、模块骨架、action 字段全表、CRUD 契约、注册三步、常见坑与验收命令。
+
+### Changed
+
+- **进程界面时间起点改为领取时刻**（原为任务创建时刻）。
+- 面板组任务提交走与 CLI 同一条严格口径（组 → 严格 board+project，成员校验一致）。
+- MD 工作台修正：能打出空格（块↔正文往返不再吃掉尾随空白）；标题不再与正文融合进
+  同一块；frontmatter 渲染成属性卡；划选不误触编辑。
+- cloud 清单页移除「CLI 等价」提示块。
+
+### Fixed
+
+- 项目组「添加成员」的 UI/UX（见上：就地选择器 + 搜索 + 归属继承）。
+
 ## [0.14.0] - 2026-11-03 wait 收尾指令模板化 + 回调提示词/持续 get 可配多条 + timegoal 面板入口 + 前缀归组改一次性命令 + 删全局默认时长
 
 ### Changed

package/README.md

@@ -268,9 +268,10 @@ nx-kv todo get --ref "旧记录" --topic fr   # 或按主题收窄
 
 ```
 src/core/          零业务语义：kvapi / fileapi（后端客户端） / attachstore（附件本地镜像） / config / errors / fstree
+src/shared/        同构纯函数：附件语法 / 双链 / frontmatter——Node 与浏览器加载同一份，零依赖
 src/modules/       功能域：system / setting / auth / group / localtask / timegoal / todo / file / bundled
 src/runtime/       装配层：registry / spec / cli / api / server
-src/web/frontend/  React 壳
+src/web/frontend/  React 壳（视图全在这里，后端不知道它们的路径）
 assets/nx-kv/            内置 skill：KV 清单操作手册（远程）
 assets/kv-waittask/         内置 skill：对话内本地任务接力（等待侧）
 assets/kv-submit/        内置 skill：需求提炼与委托提交（提交侧）
@@ -278,8 +279,20 @@ assets/kv-localget/         内置 skill：领取本目录本地任务（领取
 assets/kv-timegoal/         内置 skill：持续 N 小时任务的时间目标与提示词回显
 ```
 
-分层由 `eslint.config.js` 的 `no-restricted-imports` 强制；
-`tests/unit/registry.test.mjs` 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐。
+分层由 `eslint.config.js` 的 `no-restricted-imports` 与 `tests/unit/layering.test.mjs` 双重强制：
+
+```
+core ← 谁都不依赖        shared ← 零依赖（不许 node: / 第三方包）
+modules ← core + shared   runtime ← 装配全部          web ← 只有 shared
+```
+
+**前端够不着 modules / runtime / core**——它消费后端的唯一方式就是 HTTP `/api`。
+`tests/unit/registry.test.mjs` 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐，
+并检查面板里出现的每个 `/api` 路径都真实存在。
+
+> **改本仓库代码时**：先看项目级 skill `.claude/skills/dev-nxkv/`——它是一份施工单
+> （分层地图、模块骨架、action 字段全表、CRUD 契约、注册三步、常见坑与验收命令）。
+> 在本仓库里开工的 agent 会自动带上它。
 
 ## 给 agent 用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

package/src/core/command-table.js

@@ -0,0 +1,22 @@
+// 命令表快照：runtime 装配后写一次，模块只读。
+//
+// 为什么需要这个格子：`/api/bootstrap` 要给面板下发「每个操作对应的 CLI 命令」，
+// 而这张表由 runtime 装配（cli.js / registry.js）。模块直接 import runtime 会成环
+// （registry → modules/system → cli → registry），历史写法是用 `await import(...)`
+// 绕开：命令能跑，但分层倒了，且 loader 顺序一变就可能拿到半初始化的模块。
+//
+// 现在方向是单向的：
+//   runtime → core（写快照）    modules → core（读快照）
+// 谁都不再反过来依赖谁。没有快照时返回空数组——调用方（bootstrap）允许空表降级，
+// 面板仍能打开，只是没有 CLI 提示。
+let rows = [];
+
+/** 由 runtime 在装配完成时调用。只保留最后一次写入（CLI 的表是注册表的超集）。 */
+export function publishCommandTable(list) {
+  rows = Array.isArray(list) ? list : [];
+}
+
+/** 当前命令表快照（每行 { id, module, command, usage, http, summary }）。 */
+export function commandTable() {
+  return rows;
+}

package/src/modules/bundled/index.js

@@ -63,7 +63,6 @@ export default {
   id: 'bundled',
   title: '内置 skill 包',
   order: 50,
-  view: null,
 
   actions: [
     {

package/src/modules/docs/index.js

@@ -215,7 +215,7 @@ export default {
   id: 'docs',
   title: '文档（自有 md 树：项目/组介绍、组内描述、双链、外部只读绑定）',
   order: 12,
-  view: null, // 面板入口在组详情页与工作区 doc 页签（DocPanel），不占独立视图
+  // 面板入口在组详情页与工作区 doc 页签（DocPanel），不占独立视图
 
   resource: 'doc',
 

package/src/modules/docs/knowledge.js

@@ -190,15 +190,29 @@ function renderMd(k) {
   return lines.join('\n');
 }
 
+/**
+ * **介绍文档**：绑定优先（外部绝对路径 / 自有 rel），缺省走约定路径。
+ * 返回 { body, path }——path 给 agent 直接读盘（自有树给绝对路径）。
+ */
+async function readIntroDoc(ref, fallbackRel, { warnings, label }) {
+  if (ref && ref.path) {
+    const ext = await readExternalDoc(ref.path, { warnings, label });
+    return { body: ext.body || '', path: ref.path };
+  }
+  const rel = (ref && ref.rel) || fallbackRel;
+  const own = await readOwn(rel, { warnings, label });
+  return { body: own.body || '', path: join(paths.docsRoot(), rel) };
+}
+
 /**
  * **项目组上下文**（交付层用）：某个工作目录所属仓库所在的项目组材料。
  *
  * 与 repoKnowledge 的区别：那是「一份完整的知识报告」（CLI 给人看）；
- * 这里只取**交付时必须带上的那部分**——组定位、组介绍、本项目在组里的位置、
- * 兄弟成员的组内描述、组绑定参考文件的**可读路径**。
+ * 这里只取**交付时必须带上的那部分**——项目介绍、组定位、组介绍、
+ * 本项目在组里的位置、兄弟成员的组内描述、组绑定参考文件的**可读路径**。
  *
- * 返回 { repo:{name,key}, groups:[{name,key,desc,intro:{body,path},note,peers,docLinks}] }
- * 不在项目组里 → groups 为空数组（调用方据此不拼上下文段）。
+ * 返回 { repo:{name,key,intro:{body,path}}, groups:[{name,key,desc,intro:{body,path},note,peers,docLinks}] }
+ * 不在项目组里 → groups 为空数组（组上下文段不拼，但项目介绍照给）。
  */
 export async function groupContextFor(cwd) {
   const { loadStore, deriveKey, boardKeyOf, boardRepoKeys, normalizePathKey } = await reposBridge();
@@ -212,21 +226,14 @@ export async function groupContextFor(cwd) {
   const closure = await store.externalClosure(s);
   const groups = [];
 
+  // 项目介绍（项目级任务也要带——它回答「这个项目是干什么的」）
+  const repoIntro = await readIntroDoc(repo.doc, paths.repoDocRel(rk), { warnings, label: '项目介绍' });
+
   for (const b of s.boards) {
     const members = boardRepoKeys(b, s);
     if (!members.includes(rk)) continue;
     // 组介绍（绑定优先，缺省约定路径）
-    const introRef = b.doc;
-    const introRel = paths.boardDocRel(b.name);
-    let intro = { body: '', path: '' };
-    if (introRef && introRef.path) {
-      const ext = await readExternalDoc(introRef.path, { warnings, label: `组介绍·${b.name}` });
-      intro = { body: ext.body || '', path: introRef.path };
-    } else {
-      const rel = (introRef && introRef.rel) || introRel;
-      const own = await readOwn(rel, { warnings, label: `组介绍·${b.name}` });
-      intro = { body: own.body || '', path: join(paths.docsRoot(), rel) };
-    }
+    const intro = await readIntroDoc(b.doc, paths.boardDocRel(b.name), { warnings, label: `组介绍·${b.name}` });
     // 本项目在组里的位置
     const noteRef = (b.repoDocs || {})[rk];
     const noteOwn = await readRef(noteRef, paths.groupNoteRel(b.name, rk), { warnings, label: `组内描述·${b.name}` });
@@ -264,7 +271,7 @@ export async function groupContextFor(cwd) {
       docLinks,
     });
   }
-  return { repo: { name: repo.name, key: rk }, groups };
+  return { repo: { name: repo.name, key: rk, intro: repoIntro }, groups };
 }
 
 /**

package/src/modules/docs/links.js

@@ -5,7 +5,7 @@
 import * as paths from './paths.js';
 import * as store from './store.js';
 import { reposBridge } from './repos-bridge.js';
-import { parseWikiLinks, resolveWikiLink, normalizeWikiTarget } from './wikilink.js';
+import { parseWikiLinks, resolveWikiLink, normalizeWikiTarget } from '../../shared/wikilink.js';
 
 const baseNameOf = (p) => String(p || '').replace(/\\/g, '/').split('/').pop().replace(/\.md$/i, '');
 

package/src/modules/file/index.js

@@ -14,7 +14,6 @@ export default {
   order: 40,
   // 没有独立面板：附件在「清单」页里被引用与预览，单独开一个 tab
   // 会得到第二个「附件列表」，反而不知道以哪个为准。
-  view: null,
 
   actions: [
     {

package/src/modules/localtask/board-target.js

@@ -0,0 +1,161 @@
+// CLI/面板提交任务时的**工作组目标解析**：--board / --project → frontmatter 字段 + 落点目录。
+//
+// 纯逻辑（store 由调用方注入）：单元测试直接喂数组，不碰磁盘。
+//
+// **输入是归一化后的形状**（调用方用 repos 服务的 boardRepoKeys / deriveKey 归一）：
+//   boards[i] = { id, name, key, memberKeys: string[] }   ← 成员键（不是 repoIds）
+//   repos[i]  = { key, name, path }
+// 归一化放在调用方，是因为 repos 模块在**模块互依禁列**里（localtask 不能静态引它）。
+//
+// 语义（**正逻辑：项目优先**）：
+//   --project <key|name|path> 归属项目 = 任务挂在哪个项目上；落点目录由它推导
+//                              （进那个项目的队列）。给了它就不用管 --cwd。
+//   --board  <id|key|name>    工作组（看板）：归属项目**必须是它的成员**，一起写进
+//                              正文 frontmatter（board + project），任务才出现在组面板里。
+//   --cwd    目录             只在没有 --project 时用来指定「落在哪个队列」；
+//                              与 --board 并用时**不参与归属推断**（归属只能是项目）。
+//
+// frontmatter 字段（正文头部，写给 agent 读）：
+//   board / project          归属（组 id / 项目 key）
+//   boardIntro / projectIntro 介绍文档的**可寻址路径**（绑定优先，缺省约定路径）
+//   boardDesc / projectDesc  一句话摘要（组 desc / 项目 desc）
+//
+// 为什么不能从 cwd 反推项目：--cwd 是「队列地址」，--project 是「归属」——
+// 两件事。反推等于让地址决定归属，用户以为在挂项目，实际被目录牵着走。
+// 组内任务必须显式指明组内项目：归属不明就不该静默落在某个目录。
+import { badInput } from '../../core/errors.js';
+import { boardDocRel, repoDocRel } from '../docs/paths.js';
+
+const normPath = (p) => String(p || '').replace(/[\\/]+/g, '/').replace(/\/$/, '').toLowerCase();
+
+/**
+ * 介绍文档的**可寻址位置**（引用式：frontmatter 给路径，agent 拿到就能读盘）。
+ * 绑定优先（DocRef：自有 rel / 外部绝对路径），缺省走约定路径。
+ */
+function introPath(ref, conventionRel) {
+  if (ref && typeof ref === 'object') {
+    if (ref.rel) return ref.rel;
+    if (ref.path) return ref.path;
+  }
+  return conventionRel;
+}
+
+/** 看板按 id / key / 名称匹配（组名最像人话，agent 上下文里只有组名） */
+export function findBoard(boards, want) {
+  const w = String(want ?? '').trim();
+  if (!w) return null;
+  return (
+    (boards || []).find((b) => b.id === w) ||
+    (boards || []).find((b) => b.key === w) ||
+    (boards || []).find((b) => String(b.name || '').toLowerCase() === w.toLowerCase()) ||
+    null
+  );
+}
+
+/** 仓库按 key / 名称 / 路径匹配 */
+export function findRepo(repos, want) {
+  const w = String(want ?? '').trim();
+  if (!w) return null;
+  const wp = normPath(w);
+  return (
+    (repos || []).find((r) => r.key === w) ||
+    (repos || []).find((r) => String(r.name || '').toLowerCase() === w.toLowerCase()) ||
+    (repos || []).find((r) => normPath(r.path) === wp) ||
+    null
+  );
+}
+
+/** 看板成员键（归一化后的形状；兼容直接给 repoKeys 的用法） */
+export function memberKeysOf(board) {
+  if (!board) return new Set();
+  if (Array.isArray(board.memberKeys)) return new Set(board.memberKeys.filter(Boolean));
+  if (Array.isArray(board.repoKeys)) return new Set(board.repoKeys.filter(Boolean));
+  if (Array.isArray(board.repos)) {
+    return new Set(board.repos.map((m) => (typeof m === 'string' ? m : m && m.key)).filter(Boolean));
+  }
+  return new Set();
+}
+
+/**
+ * 解析提交目标。
+ * @param {{board?: string, project?: string, cwd?: string}} want  --board / --project / --cwd 原始值
+ * @param {{boards: Array, repos: Array}} store   仓库登记与看板（由调用方注入，归一化后）
+ * @returns {{boardId: string, boardName: string, projectKey: string, projectName: string, cwd: string, fields: object}}
+ */
+export function resolveGroupTarget(want, store) {
+  const boards = (store && store.boards) || [];
+  const repos = (store && store.repos) || [];
+  const boardWant = String(want.board ?? '').trim();
+  const projWant = String(want.project ?? '').trim();
+  const cwdWant = String(want.cwd ?? '').trim();
+  if (!boardWant && !projWant) {
+    return { boardId: '', boardName: '', projectKey: '', projectName: '', cwd: '', fields: {} };
+  }
+
+  let board = null;
+  if (boardWant) {
+    board = findBoard(boards, boardWant);
+    if (!board) {
+      throw badInput(
+        `找不到项目组「${boardWant}」（可用 nx-kv board list 看清单；id / key / 名称都认）`
+      );
+    }
+  }
+
+  // 成员集合：有组时只能在组内选（--project 必须是该组成员）
+  const memberKeys = board ? memberKeysOf(board) : null;
+  let repo = null;
+  if (projWant) {
+    repo = findRepo(repos, projWant);
+    if (!repo) {
+      throw badInput(`找不到项目「${projWant}」（可用 nx-kv repo list 看登记；key / 名称 / 路径都认）`);
+    }
+    if (memberKeys && !memberKeys.has(repo.key)) {
+      throw badInput(
+        `项目「${repo.name || repo.key}」不是项目组「${board.name}」的成员（先 nx-kv board assign 挂进去）`
+      );
+    }
+    // --project 与 --cwd 都给了却指向不同项目 → 用错了，不静默取一个
+    if (cwdWant && repo.path && normPath(cwdWant) !== normPath(repo.path)) {
+      throw badInput(
+        `--cwd 指向「${cwdWant}」，--project 指向「${repo.name || repo.key}」（${repo.path}）——不是同一个项目；给了 --project 就不用再给 --cwd`
+      );
+    }
+  } else if (board) {
+    // 有组就必须有归属项目：组内任务不能归属不明。
+    // 列出成员**名字**（用户真会敲进 --project 的值）；认不出名字的退回 key。
+    const members = [...(memberKeys || [])].map((k) => {
+      const r = (repos || []).find((x) => x.key === k);
+      return r && r.name ? r.name : k;
+    });
+    throw badInput(
+      `--board「${board.name}」的任务要指明归属项目：加 --project <项目>` +
+        (members.length ? `（本组成员：${members.join(' / ')}）` : '')
+    );
+  }
+
+  // frontmatter 字段：**归属**（board id / project key）+ **介绍引用**（路径 + 一行摘要）。
+  // 介绍用引用式而不是内联正文：正文是 md 文件、路径即地址，agent 拿到就能读盘；
+  // 内联既撑爆 frontmatter，又会在介绍更新后留下过期副本。
+  const fields = {};
+  if (board) {
+    fields.board = board.id;
+    fields.boardIntro = introPath(board.doc, boardDocRel(board.name));
+    fields.boardDesc = String(board.desc || '').trim();
+  }
+  if (repo) {
+    fields.project = repo.key;
+    fields.projectIntro = introPath(repo.doc, repoDocRel(repo.key));
+    fields.projectDesc = String(repo.desc || '').trim();
+  }
+
+  return {
+    boardId: board ? board.id : '',
+    boardName: board ? board.name || '' : '',
+    projectKey: repo ? repo.key : '',
+    projectName: repo ? repo.name || repo.key : '',
+    // 落点：有项目就用项目登记的路径（进它的队列）；否则调用方给的 cwd 说了算
+    cwd: repo ? repo.path || '' : '',
+    fields,
+  };
+}

package/src/modules/localtask/index.js

@@ -43,10 +43,30 @@ const renderTask = (t) =>
     `#${t.id}  [${STATUS_TAG[t.status] || t.status}]  ${t.text}`,
     `  创建: ${t.createdAt}`,
     t.consumedAt ? `  领取: ${t.consumedAt}` : '',
+    // 附件清单（正文里的 ![名](fileId) 嵌入；本地已有 → 直接给绝对路径）
+    ...(t.attachments || []).map(
+      (a) => `  附件:   ${a.localPath || a.name}${a.localPath ? '' : `（未同步；nx-kv file sync --ids ${a.id}）`}`
+    ),
   ]
     .filter(Boolean)
     .join('\n');
 
+// `localtask attachments` 的人读输出（与 todo attachments 同构）
+function renderTaskAttachments(d) {
+  const lines = [
+    `#${d.task.id}  附件 ${d.count} 个 · 本地目录: ${d.localDir}（自动下载 ${d.autoSync ? '开' : '关'}）`,
+  ];
+  if (!d.count) {
+    lines.push('  （这条任务没有引用附件）');
+    return lines.join('\n');
+  }
+  for (const a of d.attachments) {
+    lines.push(`  ${a.kind === 'image' ? '图片' : '附件'}  ${a.name}  [${a.id}]`);
+    lines.push(`      ${a.localPath || '（未同步；nx-kv file sync --ids ' + a.id + '）'}`);
+  }
+  return lines.join('\n');
+}
+
 function renderAdd(d) {
   const where = d.isGlobal ? '全局任务（共享池）' : `主题「${d.name}」`;
   const head = `#${d.task.id} [${d.task.status}] ${d.task.text}`;
@@ -114,7 +134,6 @@ export default {
   id: 'localtask',
   title: '本地任务（= Web「本地任务」页）',
   order: 20,
-  view: () => import('./view.jsx'),
 
   // CRUD 资源声明：主题任务的增删查改齐备，CLI 与面板都能调用
   resource: 'localtask',
@@ -135,9 +154,18 @@ export default {
       // 领任务（见 localtask.claim），查看走 `localtask show`。HTTP 路由不变。
       cli: ['localtask', 'show'],
       http: ['GET', '/api/localtasks/item'],
-      summary: '查看单条任务（按 --id，定位到 --cwd 主题或 --key）',
+      summary: '查看单条任务（按 --id，定位到 --cwd 主题或 --key）；正文引用附件时带附件清单与本地路径（自动下载跟随本机设置）',
       flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD, key: KEY },
-      run: (ctx) => service.getTask({ id: ctx.id, cwd: ctx.cwd, key: ctx.key }),
+      run: async (ctx) => {
+        const task = await service.getTask({ id: ctx.id, cwd: ctx.cwd, key: ctx.key });
+        // 附件标注（任务 #15）：解析正文嵌入 + 按设置自动下载 + 标本地路径。
+        // fail-open：标注坏了照常返回任务本体。
+        const { annotateTaskDelivery } = await import('../tasktool/attach.js');
+        const att = await annotateTaskDelivery(task).catch(() => null);
+        return att
+          ? { ...task, attachments: att.task.attachments, ...(att.sync ? { attachmentsSync: att.sync } : {}) }
+          : task;
+      },
       render: renderTask,
     },
     {
@@ -244,15 +272,26 @@ export default {
       cli: ['localtask', 'add'],
       http: ['POST', '/api/localtasks'],
       summary:
-        '向某主题（工作目录）的队列回填一条任务（有 wait 在等则即时投递，否则排队）；--global 推到全局共享池；--duration 给任务带时间目标（领取即计时，完成前必须 check）',
+        '向某主题（工作目录）的队列回填一条任务（有 wait 在等则即时投递，否则排队）；--global 推到全局共享池；--duration 给任务带时间目标（领取即计时，完成前必须 check）；--board/--project 让任务带工作组语义（正文 frontmatter：board + project + 双方介绍引用），并落进该项目的队列；正文自带 frontmatter 时同样认归属——补介绍引用，落点跟到项目队列（显式给过 --cwd 时不挪窝）',
       args: ['text'],
       flags: {
-        cwd: CWD,
+        cwd: {
+          type: 'string',
+          hint: '工作目录（作为主题；默认当前目录）。归属由 --project 决定：给了 --project 就用它推导落点，这里再给且不一致会报错',
+        },
         summary: { type: 'string', hint: '顺带刷新该主题的当前现状（可选）' },
         global: {
           type: 'boolean',
           hint: '推到全局主题（共享池）：任何目录的 wait 在本地空时自动领取；--cwd 被忽略',
         },
+        board: {
+          type: 'string',
+          hint: '工作组（看板）id / key / 名称：任务正文自动带上 frontmatter（board + 组介绍引用），该任务才会出现在组面板里；必须同时给 --project 指明归属项目',
+        },
+        project: {
+          type: 'string',
+          hint: '归属项目（仓库 key / 名称 / 路径）：任务挂在哪个项目上，落点目录由它推导，frontmatter 带上 project + 项目介绍引用；配 --board 时必须是该组成员',
+        },
         duration: {
           type: 'string',
           hint: '时间目标时长（2h / 90m / 5小时）：领取即计时，未到点不许标完成',
@@ -260,15 +299,20 @@ export default {
         'goal-prompt': { type: 'string', hint: '时间目标的附加要求（随 check 指令一起固化，可省）' },
         goalPrompt: { type: 'string', hint: '同 --goal-prompt（驼峰写法）' },
       },
-      run: (ctx) => {
-        const gp = ctx.goalPrompt ?? ctx['goal-prompt'];
-        const timegoal = ctx.duration || gp ? { duration: ctx.duration, prompt: gp } : undefined;
-        return service.addTask({
+      run: async (ctx) => {
+        // 派任务编排已迁 tasktool/add.js（任务工具语义归 tasktool；命令名不变）。
+        // 落点判定（--board/--project 严格口径 / 正文 frontmatter fail-open）只此一份实现，
+        // CLI、HTTP、面板提交同走这一条链路。
+        const { submitTask } = await import('../tasktool/add.js');
+        return submitTask({
           text: ctx.text,
           cwd: ctx.cwd,
           summary: ctx.summary,
           global: ctx.global,
-          timegoal,
+          board: ctx.board,
+          project: ctx.project,
+          duration: ctx.duration,
+          goalPrompt: ctx.goalPrompt ?? ctx['goal-prompt'],
         });
       },
       render: renderAdd,
@@ -310,6 +354,51 @@ export default {
             ? '（时间目标已清除）'
             : ''),
     },
+    {
+      // 附件追加（与云端 todo attach 同构）：上传/复用 fileId → markdown 嵌入正文末尾。
+      // 面板编辑器贴的是同一条语法（components/md/attachments.js），两端渲染一致。
+      id: 'localtask.attach',
+      cli: ['localtask', 'attach'],
+      http: ['POST', '/api/localtasks/attach'],
+      summary: '给任务追加附件：--path 上传本机文件，或 --fileId 追加已上传附件，以 markdown 嵌入正文末尾（不替换正文）',
+      flags: {
+        id: { type: 'number', required: true, hint: '任务编号' },
+        cwd: CWD,
+        key: KEY,
+        path: { type: 'string', hint: '本机文件路径（先上传再嵌入）' },
+        fileId: { type: 'string', hint: '已上传附件的 id（32 位 hex，可带扩展名）' },
+        name: { type: 'string', hint: '嵌入文字与本地文件名（默认取原文件名）' },
+        kind: { type: 'string', hint: 'image | file（不给按文件名/扩展名判）' },
+        accessLevel: { type: 'string', hint: 'public | private | protected（默认 public；仅 --path 上传时生效）' },
+      },
+      run: async (ctx) => {
+        const { attachToTask } = await import('../tasktool/attach.js');
+        return attachToTask({
+          id: ctx.id,
+          cwd: ctx.cwd,
+          key: ctx.key,
+          path: ctx.path,
+          fileId: ctx.fileId,
+          name: ctx.name,
+          kind: ctx.kind,
+          accessLevel: ctx.accessLevel,
+        });
+      },
+      render: (d) =>
+        `已附加 ${d.fileId}（${d.kind === 'image' ? '图片' : '文件'}）到主题「${d.name}」#${d.task.id}\n嵌入: ${d.markdown}`,
+    },
+    {
+      id: 'localtask.attachments',
+      cli: ['localtask', 'attachments'],
+      http: ['GET', '/api/localtasks/attachments'],
+      summary: '列出某条任务引用的附件（正文里的 ![名](fileId) 嵌入），以及本地是否已有（给 agent 直接读本地文件）',
+      flags: { id: { type: 'number', required: true, hint: '任务编号' }, cwd: CWD, key: KEY },
+      run: async (ctx) => {
+        const { listTaskAttachments } = await import('../tasktool/attach.js');
+        return listTaskAttachments({ id: ctx.id, cwd: ctx.cwd, key: ctx.key });
+      },
+      render: renderTaskAttachments,
+    },
     {
       id: 'localtask.remove',
       cli: ['localtask', 'remove'],