@gavinc-cn/touchstone-dsh 0.0.0-stage → 0.1.1

package/README.zh.md

@@ -0,0 +1,318 @@
+<div align="center">
+
+# Touchstone（试金石）
+
+**AI agent 驱动的自动化测试平台。** 把它指向一个代码仓库，它会读代码、写用例、跑用例，
+把失败沉淀成 bug 报告，修完再复测一遍。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@gavinc-cn/touchstone-dsh?logo=npm&color=cb3837)](https://www.npmjs.com/package/@gavinc-cn/touchstone-dsh)
+[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB.svg)](https://www.python.org/)
+[![Node 22.19+ | 24+](https://img.shields.io/badge/Node-22.19%2B%20%7C%2024%2B-339933.svg)](https://nodejs.org/)
+[![DeepSeek Harness plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4D6BFE.svg)](https://github.com/deepseek-ai/deepseek-harness)
+
+[English](README.md) | 中文
+
+<img src="docs/images/board.png" alt="Touchstone 开发看板" width="920">
+
+</div>
+
+## Touchstone 是什么
+
+Touchstone 把「我们真该多测一点」变成一条持续转动的流水线。你登记一个项目——源码目录、
+工作目录、环境标签、以及要求 agent 遵守的项目约定——Touchstone 就会通过
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）驱动 AI agent：
+**生成测试用例 → 执行 → 把失败写成 bug 报告 → 修代码 → 再复测**。所有产物都以可直接审阅的形式
+落在磁盘上：Markdown 写的案例库、`bug_report/` 目录、以及逐轮日志。
+
+它不是「跑一遍我的测试」的一次性 CLI。Touchstone 的核心是**多轮常驻 agent 会话**：一个任务在同一
+会话里一轮接一轮地跑，上下文不断档，agent 记得自己试过什么。统一队列保证同一个项目同一时刻只有
+一个写者（不会有两个 agent 同时改同一份检出），并且全流程可观测——逐轮实时日志、可渲染的会话窗口、
+以及基于 SSE 的看板。
+
+Touchstone 是**本地运行**的：Python 站点 + SQLite + 文件系统工作区。除了你的 `dsh` 宿主发起的模型
+调用之外，数据不出本机。
+
+## 主要特性
+
+- **六类任务**覆盖完整测试闭环：探索 / 回归 / 压测 / 修复 / 复测 / 修例，每类都走七阶段生命周期
+  （生成用例 → 测试 → 生成报告 → 报告分析 → 问题修复 → 重新部署 → 复测）。
+- **案例库而不是测试日志**。用例是可读的 Markdown（每个用例 `case.md` + `status.md`，每层目录一个
+  `INDEX.md`）。agent 跨任务读写同一份案例库；用例写错了，你直接改文件就能修。
+- **bug 报告是一等产物**。失败会写成结构化报告（严重程度、复现步骤、日志证据、关联用例），并可在
+  界面上直接派生成修复 / 复测 / 修例任务。
+- **按项目的统一队列**。任务、看板卡片、会话消息共用同一个项目级串行位；排队位次、当前占用者与
+  判定证据都可查，不靠猜。
+- **面向 agent 开发的看板**。卡片可以起跑、排队、阻塞、完成各自的 agent 会话；需要时在独立的
+  `git worktree` 里跑，探索性改动不碰你的主检出。
+- **会话可观测**。完整渲染任意 agent 会话的消息、思考、工具调用与返回；可续聊、可往当前轮注入、
+  可压缩、可 fork、也可通过 fork 回退到更早的节点。
+- **内置压测**。压测任务先让 agent 产出场景与脚本，之后由平台自己发压，一个任务可跑 N 次，每次都有
+  指标、图表与 Markdown/JSON 报告。
+- **可选集成**。飞书（Lark）推送通知与卡片双向作答；案例库的可选语义检索（RAG）。
+- **自包含技术栈**。后端：Python 标准库 + 4 个小依赖；前端：React + Vite；存储：SQLite + 普通文件。
+  Linux 与 Windows 均可运行。
+
+## 界面截图
+
+开发看板——五列卡片、任务条目内联展示、项目级排队徽标：
+
+![开发看板](docs/images/board.png)
+
+测试任务——六类任务、轮次、状态与逐任务操作：
+
+![测试任务](docs/images/tasks.png)
+
+会话窗口——从 `dsh` 会话存储渲染出的完整对话（消息、思考、工具调用），带回复、审批与模型控件：
+
+![会话窗口](docs/images/session.png)
+
+卡片详情——描述、定时开工、父任务依赖、绑定会话与评论：
+
+![卡片详情](docs/images/card-detail.png)
+
+## 工作原理
+
+```mermaid
+flowchart LR
+  U[浏览器] -->|REST + SSE| S["Touchstone 站点<br/>Python 标准库 · SQLite · 文件"]
+  S -->|"/touchstone-agent<br/>常驻会话"| D["dsh 宿主<br/>DeepSeek Harness"]
+  D -->|"读 / 改 / 执行"| R["你的代码仓库"]
+  D --> C[("案例库<br/>free_style/")]
+  D --> B[("bug 报告<br/>bug_report/")]
+  S --- C
+  S --- B
+```
+
+1. **建项目**：Touchstone 记录仓库路径、工作目录、环境标签、可选的项目能力 skill，以及每轮首轮
+   提示词都会注入的自由文本约定。
+2. **建任务**：选类型（例如「探索」）与终点阶段（例如「生成报告」），入该项目的队列。
+3. **多轮会话执行**：Touchstone 经 `dsh` 插件新建或续接一个常驻会话，下发本轮提示词；过程实时回流
+   到界面，并写入 `<工作目录>/.web/task_<id>_round_<n>.log`。
+4. **产物落到工作目录**：新用例进 `free_style/`，bug 报告进 `bug_report/`，监控状态进 `.live/`——
+   你像审代码一样审它们。
+5. **后段任务闭环**：报告可派生修复任务，修复可派生复测任务，被否决的报告可派生修例任务；当任务的
+   终点越过「生成报告」时，平台会自动追加后段阶段任务。
+
+### 任务类型
+
+| 类型 | agent 做什么 | 常见终点 |
+|------|--------------|----------|
+| 探索 | 读代码并把新用例写进案例库 | 生成报告 |
+| 回归 | 重跑已有用例（可限定提交日期范围） | 生成报告 |
+| 压测 | 产出压测场景 + 驱动脚本，随后由平台发压 | 生成报告 |
+| 修复 | 分析 bug 报告、改代码、部署并复测 | 问题修复 / 重新部署 / 复测 |
+| 复测 | 针对一份 bug 报告复验（仅复测 / 部署后复测 / 仅部署） | 复测 |
+| 修例 | 判定报告对应的用例本身有误，改写用例 | 修订用例 |
+
+### 核心概念
+
+| 概念 | 含义 |
+|------|------|
+| 项目 | 一个仓库 + 工作目录 + 智能体绑定 + 环境标签 + 项目约定 |
+| 任务 | 一个排队单元：任务类型、阶段范围、停止条件与轮次历史 |
+| 轮次 | 任务会话里的一次「提示词 → agent 执行」循环 |
+| 案例库 | `<工作目录>/free_style/`：Markdown 用例、状态文件与逐层索引 |
+| bug 报告 | `<工作目录>/bug_report/<时间戳>_FS_<标题>/`：一条用例的失败档案 |
+| 卡片 | 看板条目，可起跑、排队并驱动自己的 agent 会话 |
+| 队列 | 任务 / 卡片 / 会话消息共享的项目级串行位 |
+
+## 快速开始
+
+### 环境要求
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| Python | 3.12+ | 运行站点（实测 3.12） |
+| Node.js | 22.19+ 或 24+ | 运行 `dsh` 宿主（仅构建前端时 Node 18+ 即可） |
+| DeepSeek Harness（`dsh`） | 当前版本 | agent 执行——插件形态必需 |
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/gavinc-cn/touchstone-dsh.git
+cd touchstone-dsh
+python3 -m pip install -r requirements.txt
+```
+
+### 2. 启动站点（独立形态）
+
+```bash
+./touchstone.sh start          # 首次启动会自动构建前端，然后监听 127.0.0.1:4601
+./touchstone.sh status         # 查看 PID 与实际端口
+./touchstone.sh stop
+```
+
+浏览器打开 <http://127.0.0.1:4601>。
+
+首次启动会种子一个 `admin` 账号。若未设置 `TS_ADMIN_PASSWORD`，平台会随机生成一次性初始口令，
+**只在启动横幅打印一次**：
+
+```bash
+grep '一次性初始口令' .run/server.log     # 或：./touchstone.sh status
+```
+
+首次登录会被要求改密。想跳过一次性口令（以及强制改密），在首次启动前设置
+`TS_ADMIN_PASSWORD=<你的口令>` 即可。
+
+> 独立形态给的是完整站点——项目、案例库、bug 报告、看板、队列、监控都能用；但**agent 执行需要
+> 插件形态**（见下），因为 agent 跑在 `dsh` 宿主进程里。
+
+### 3. 以 `dsh` 插件形态运行（推荐：启用 agent 执行）
+
+插件把 Touchstone 嵌进 `dsh` Web 界面（侧栏入口 + 面板），并让 Touchstone 能驱动宿主进程内的常驻
+agent 会话。
+
+**方式 A —— 从 npm 安装（自包含包：整个平台 + 预构建前端都在包里）:**
+
+```bash
+npx @deepseek-ai/dsh web          # 1) 先启动一次 dsh 宿主（会创建 ~/.dsh/profiles/web）
+dsh plugin --profile web add @gavinc-cn/touchstone-dsh   # 2) 装插件包
+# 3) 把包名选进 profile 清单（等同 Plugins 面板里那一行的开关）：
+node ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/dsh-plugin/scripts/select-bundle.mjs \
+  ~/.dsh/profiles/web/package.json
+# 4) 重启 dsh web，打开 http://127.0.0.1:3080，用侧栏里的 Touchstone 入口（Alt+T 开关面板）
+```
+
+平台自身的 Python 依赖走 pip，npm 不管：
+
+```bash
+pip install -r ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/requirements.txt
+```
+
+**不需要配 `repoDir`**：包里带着 `server.py` 与 `webui/dist-plugin`，插件缺省就用包自身目录。
+
+**方式 B —— 从检出安装（开发用）:**
+
+```bash
+cd touchstone-dsh
+./dsh-plugin/install.sh           # 幂等安装本检出到 profile
+```
+
+安装脚本会打印**可选**的 profile 覆盖（指向本机工作副本、或指定解释器）；不写就用包自身目录：
+
+```yaml
+- id: touchstone
+  config: { repoDir: /path/to/touchstone-dsh, pythonPath: /path/to/python3 }
+```
+
+两种形态默认共用同一个数据库（`~/.touchstone/touchstone.db`），运行时互斥：第二个实例会拒绝启动，
+并打印当前占用者。
+
+### Windows
+
+跨平台启停器提供同一套命令：
+
+```bash
+python touchstone.py start | stop | restart | status | build | test
+```
+
+### 界面里的第一步
+
+1. 登录；若用的是一次性口令，先去 **设置 → 修改密码**。
+2. **添加项目**——源码目录、工作目录（默认 `<项目目录>/.touchstone`）、环境标签，以及要求 agent
+   遵守的约定。案例库与 bug 报告目录由平台派生并自动创建。
+3. 新建任务（或建一张看板卡），等队列调度。逐轮日志实时刷新，会话窗口随对话增长即时渲染。
+
+## 配置
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `TS_PORT` / `TS_HOST` | `4601` / `127.0.0.1` | 监听地址；`TS_HOST=0.0.0.0` 可对局域网开放 |
+| `TS_PYTHON` | `python3` | 启停器使用的解释器（需装好运行依赖） |
+| `TOUCHSTONE_DB` | `~/.touchstone/touchstone.db` | SQLite 数据库，必须放本地盘——文件锁在 CIFS/网盘上不可用 |
+| `TS_ADMIN_PASSWORD` | *（随机，打印一次）* | `admin` 初始口令；设了就跳过强制改密 |
+| `TS_WEB_DIR` | `webui/dist` | 站点托管的前端静态目录 |
+| `TOUCHSTONE_RUN_DIR` | 仓库内 `.run/` | PID / 日志 / 端口标记文件目录 |
+| `TS_EXT_DIR` | `extensions` | 内置资产清单根目录 |
+| `TS_ARCHIVE_SYNC` | `1` | 看板「已完成」与 `dsh` 会话归档双向同步（置 `0` 关闭） |
+| `TS_DSH_PROFILE` / `TS_DSH_PYTHON` | `web` / 自动探测 | 插件安装脚本使用的 `dsh` profile 与解释器 |
+
+项目工作目录下的运行路径：
+
+| 路径 | 内容 |
+|------|------|
+| `free_style/` | 案例库（用例、状态文件、逐层索引） |
+| `bug_report/` | bug 报告，一份报告一个目录 |
+| `.web/` | 逐轮日志、对话日志、压测指标与报告 |
+| `.live/live.json` | 监控页数据源（agent 运行状态） |
+| `board_media/` | 粘贴到看板卡片的附件 |
+
+## 能力与边界
+
+| 领域 | 支持情况 |
+|------|----------|
+| agent 会话 | 新建、续接、回复、往当前轮注入、中断、compact 压缩、fork、按 fork 回退、模型与权限档切换 |
+| 会话可观测 | 完整对话渲染、归档状态、附件预览、实时状态流（零状态轮询） |
+| 任务 | 六类型、七阶段、停止条件、日期范围限定、逐轮日志、重启、继续 |
+| 看板 | 五列卡片、拖拽、排队位次、父任务依赖、定时开工、回收站、独立 worktree |
+| 案例库 | 派生索引、按变更文件做复测粗筛、可选语义检索（RAG） |
+| 压测 | 场景校验、并发发压、秒级指标、图表、每次运行独立的 Markdown/JSON 报告 |
+| 通知 | 飞书推送、入站指令、在聊天卡片上直接作答 |
+| 多用户 | 登录、admin/普通用户、所有按项目进入的接口都做归属校验 |
+
+如实说明的已知限制：
+
+- **界面目前只有中文。**
+- **agent 执行必须走插件形态**；独立形态是「没有 agent 的站点」。
+- **回退与「压缩并新建」是语义近似**——回退是从更早的节点另起一支（原会话保留），不是原地截断。
+- **模型请求失败没有错误横幅**——`dsh` 没有对应事件通道，会话窗只能显示宿主真实回报的内容。
+- **Windows 启停器已实现，但 `dsh` 在 Windows 上尚未实机验证。**
+- **端到端测试脚本不随本仓分发**（见下），因此 `test-full` 与 `test-ui` 只会提示跳过。
+
+## 仓库结构
+
+```
+touchstone-dsh/
+├── server.py            HTTP 站点：路由、鉴权、REST、SSE、静态前端
+├── runner.py            任务执行引擎与按项目调度
+├── waitq.py             统一队列模型（「下一个谁跑」的唯一权威）
+├── board.py             开发看板：卡片、门禁、agent 会话、归档同步
+├── chat.py              会话对话：排队消息与注入
+├── prompts.py           逐轮提示词模板（按任务类型与阶段）
+├── sessparse.py         读取 dsh 会话存储，还原成可渲染的对话
+├── dshdriver.py         dsh 进程内 agent 驱动的客户端
+├── dshevents.py         把 dsh 状态流折进进程内注册表
+├── rag.py               案例库可选语义检索
+├── loadgen.py           内置压测引擎（场景、指标、报告）
+├── feishu.py            飞书集成
+├── db.py                SQLite 数据层
+├── builtin_prompts/     注入首轮提示词的提示词资产
+├── dsh-plugin/          dsh 插件包（Node 薄壳 + 驱动 + 客户端 bundle）
+├── extensions/          设置页可一键安装的内置资产
+├── webui/               React + Vite 前端
+├── tests/               pytest / vitest 套件与隔离实例夹具
+└── touchstone.sh|py|cmd 启停入口（Linux / 跨平台 / Windows）
+```
+
+## 开发
+
+```bash
+./touchstone.sh build        # 安装前端依赖并构建 webui/dist
+./touchstone.sh test         # 后端 pytest + 前端 vitest
+./touchstone.sh test-full    # 追加隔离实例 e2e（本仓不随附这些脚本）
+./touchstone.sh test-ui      # Playwright e2e（需站点在跑；本仓不随附这些脚本）
+cd webui && npm run dev      # 前端开发服务器 :5173，/api 代理到 :4601
+```
+
+可选的提交门禁：
+
+```bash
+git config core.hooksPath githooks   # pre-commit 跑测试快层（SKIP_TS_TESTS=1 单次跳过）
+```
+
+测试矩阵与前置条件见 [tests/README.md](tests/README.md)。
+
+## 安全说明
+
+- 站点默认只监听 `127.0.0.1` 并要求登录。用 `TS_HOST=0.0.0.0` 对外暴露等于把它放进你的网络里，
+  请有意为之。
+- 所有按项目进入的接口先做归属校验；`admin` 是唯一管理员，不可改名或删除。
+- agent 以你配置的权限档运行，默认是限制最松的一档（免审批）。方便，但也锋利：**把它指向你在意的
+  仓库之前，请先看清项目约定与权限档。**
+- 口令存储沿用本项目既定的算法（新口令为无盐 MD5，历史种子账号为 PBKDF2-SHA256）。请把它当作
+  本地开发级别的口令存储来对待。
+
+## 许可证
+
+[MIT](LICENSE) © Touchstone contributors

package/agents.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Touchstone 本机 AI CLI 扫描：供项目配置"智能体路径"下拉选择。
+
+扫描顺序：PATH（shutil.which）→ 常见安装目录，找到即止；版本探测 --version 2s 超时。
+"""
+
+import glob
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+
+# 支持的 agent 清单: (展示名, 可能的可执行名元组)。
+# 2026-10-03（P7b 退场删除，B1）：产品入口收敛为 **dsh 插件形态**，kimi / opencode /
+# claude / hermes 四个 CLI 条目不再扫描（对应族已删除）；dsh 可执行仍扫——它是
+# 「插件·进程内」条目的 path/version 来源。
+# 2026-10-04（B7）：扫描结果只剩「插件·进程内」一条（见 scan_agents），本表的展示名
+# 自此仅作文档用，实际用于定位 dsh 可执行（PATH → 常见安装目录）。
+AGENT_DEFS = (
+    ("dsh（DeepSeek Harness）", ("dsh",)),
+)
+
+# 退场族的旧虚拟条目前缀（kimi web / opencode serve 驱动，P7b 删除）：扫描不再产出，
+# 仅「存量 agent_path 的归族」仍要认出来 —— 归 RETIRED_FAMILY 由起跑处给明确报错。
+LEGACY_WEB_PREFIXES = ("kimi-web:", "opencode-web:")
+
+# 退场族标记（P7b，2026-10-03）：agent_path 仍是旧族可执行名或旧虚拟前缀时归此族。
+# 存量库里的绑定由 migrate_p7b.py 改写（`dsh-plugin:<dsh 路径>` 或空串）；未改写前
+# 起跑处据此返回 RETIRED_MSG，而不是静默按 dsh 跑（dsh 宿主里没有旧会话）或
+# AttributeError（驱动模块已删）。
+RETIRED_FAMILY = "retired"
+RETIRED_MSG = "该智能体族已下线，请在项目设置里改绑 dsh 插件"
+
+# dsh 插件驱动前缀（路线 A）：项目 agent_path 存 "dsh-plugin:" 表示走 **dsh 宿主进程内**
+# 的 agent 运行时（dsh-plugin/lib/agent-driver.js 持有的会话池），不再 spawn
+# `dsh --profile headless` 子进程。前缀后可跟任意提示串（如 dsh 可执行路径）但平台不使用：
+# 驱动地址经环境变量 TS_AGENT_DRIVER_URL 下发（见 dshdriver.py），不依赖本机路径。
+DSH_PLUGIN_PREFIX = "dsh-plugin:"
+
+# 「插件·进程内」条目展示名（前端「智能体」下拉的唯一选项）。P7b B7（2026-10-04）
+# 起由 scan_agents 直接产出为**唯一一条**，裸 dsh CLI 行不再返回（见 scan_agents docstring）。
+PLUGIN_ENTRY_NAME = "dsh（插件·进程内）"
+
+# PATH 之外常出现的安装目录（按已知部署习惯）
+EXTRA_DIRS = [
+    "/usr/local/bin",
+    os.path.expanduser("~/.local/bin"),
+    "/bin/versions/node",
+    os.path.expanduser("~/.npm-global/bin"),
+]
+# Windows：npm 全局 shim（kimi.cmd / claude.cmd 等）所在目录
+# （shutil.which 走 PATH 也能命中，此目录兜底 PATH 被裁剪的安装方式）
+if os.name == "nt":
+    _appdata = os.environ.get("APPDATA")
+    if _appdata:
+        EXTRA_DIRS.append(os.path.join(_appdata, "npm"))
+# 递归进 versions 下各 node 版本的 bin/
+VERSIONS_BIN_GLOB = "/bin/versions/node"
+# conda/mamba 各虚拟环境的 bin 目录（glob 模式，覆盖常见安装位置；
+# 如 hermes 常被装进某个 conda 环境的 bin/）
+CONDA_ENV_BIN_GLOBS = [
+    "/opt/miniconda3/envs/*/bin",
+    "/opt/anaconda3/envs/*/bin",
+    os.path.expanduser("~/miniconda3/envs/*/bin"),
+    os.path.expanduser("~/anaconda3/envs/*/bin"),
+]
+
+
+def _search_extra(name):
+    """在扩展目录中查找 name 可执行文件，返回路径或 None。"""
+    candidates = []
+    for d in EXTRA_DIRS:
+        if not os.path.isdir(d):
+            continue
+        if d == VERSIONS_BIN_GLOB:
+            for ver in os.listdir(d):
+                candidates.append(os.path.join(d, ver, "bin", name))
+        else:
+            candidates.append(os.path.join(d, name))
+    for p in candidates:
+        if os.path.isfile(p) and os.access(p, os.X_OK):
+            return p
+    # conda/mamba 虚拟环境 bin：glob 展开各环境目录后逐个匹配
+    for pat in CONDA_ENV_BIN_GLOBS:
+        for bindir in sorted(glob.glob(pat)):
+            p = os.path.join(bindir, name)
+            if os.path.isfile(p) and os.access(p, os.X_OK):
+                return p
+    return None
+
+
+def _probe_version(path):
+    """运行 --version（2s 超时），失败返回空串。
+    cwd 用系统临时目录（跨平台；原写死 /tmp 在 Windows 不存在会静默失败）。"""
+    try:
+        out = subprocess.run([path, "--version"], capture_output=True, text=True,
+                             encoding="utf-8", errors="replace",
+                             timeout=2, cwd=tempfile.gettempdir())
+        text = (out.stdout or out.stderr).strip().splitlines()
+        return text[0][:120] if text else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def scan_agents():
+    """扫描本机 dsh 可执行，返回**产品入口单条目** [{name, path, version, found}]。
+
+    P7b B1 起扫描只认 dsh；**B7（2026-10-04）再收敛为只回一条**「dsh（插件·进程内）」
+    （`path = dsh-plugin:<dsh 路径>`，进程内会话池：多轮续接/插话/实时事件流）。
+
+    为什么仍要定位 dsh 可执行：该条目的 path（前缀后的提示串）与 version 都取自它
+    （`--version` 探测）；但**裸 dsh CLI 行不再返回给前端**——它属退场族
+    （`agent_family` 对 basename == "dsh" 判 `retired`，起跑处必报 `RETIRED_MSG`），
+    列进「智能体」下拉就是纯误选陷阱（用户 2026-10-04 报告「同一个 dsh 出现两条」）。
+
+    dsh 未找到时返回同名的 `found=False` 条目（前端显示「dsh（插件·进程内）未找到」），
+    保持「下拉里有且只有这一条」的读侧不变量。
+    """
+    path = ""
+    for _name, bins in AGENT_DEFS:
+        for b in bins:
+            path = shutil.which(b) or _search_extra(b)
+            if path:
+                break
+        if path:
+            break
+    return [{"name": PLUGIN_ENTRY_NAME,
+             "path": DSH_PLUGIN_PREFIX + path if path else "",
+             "version": _probe_version(path) if path else "",
+             "found": bool(path)}]
+
+
+def agent_family(agent_path):
+    """归族：只可能返回 `"dsh_plugin"`（可跑）或 `RETIRED_FAMILY`（退场族，起跑处报错）。
+
+    - `dsh-plugin:` 前缀 → `dsh_plugin`：产品唯一入口（dsh 宿主进程内 agent 运行时，
+      见 dshdriver.py）。前缀判定必须先于 basename——该串不是有效可执行路径；
+    - 空 `agent_path`（db 默认 `''`）与未知可执行名 → `dsh_plugin`：2026-10-03 起
+      默认族由 kimi 改为 dsh 插件（产品入口收敛）；
+    - kimi / opencode / claude / hermes / deepseek(dsh CLI) 旧可执行名，以及
+      `kimi-web:` / `opencode-web:` 两个旧虚拟前缀 → `RETIRED_FAMILY`（P7b 删除的
+      五族，2026-10-03）。存量项目由 `migrate_p7b.py` 改写 agent_path；未改写的
+      项目在起跑处得到 `RETIRED_MSG` 明确提示。
+    """
+    ap = (agent_path or "").strip()
+    if ap.startswith(DSH_PLUGIN_PREFIX):
+        return "dsh_plugin"
+    if ap.startswith(LEGACY_WEB_PREFIXES):
+        return RETIRED_FAMILY            # kimi-web: / opencode-web:（旧虚拟条目）
+    name = os.path.basename(ap).lower()
+    if any(h in name for h in ("kimi", "opencode", "claude", "hermes", "deepseek")):
+        return RETIRED_FAMILY            # 旧 CLI 族可执行名
+    if name == "dsh":
+        # dsh CLI（--profile headless）已退场：只保留插件形态（每轮独立会话、无续接）
+        return RETIRED_FAMILY
+    # 空 agent_path（db 默认 ''）与未知可执行名的默认族：本项目已收敛为「产品入口
+    # 只有 dsh 插件形态」（2026-10-03 方案 §七 D1/D2），故默认走 dsh_plugin；
+    # 要跑其他族须在项目里显式选。此前默认 "kimi"，会让未配置项目静默按 kimi 跑。
+    return "dsh_plugin"
+
+
+# 各 agent 族的 skill 目录约定（2026-08-31 从各 CLI 安装产物与本机磁盘实况验证，勿凭记忆改）：
+# 族 -> (用户级目录元组, 项目级相对目录元组)，SKILL.md 位于各目录的子目录下。
+# 产品只剩 dsh 插件一族：`dsh-skill-filesystem` 实测扫描 `<project>/.agents/skills`
+# （project-agents）与 `~/.agents/skills`（user-agents），另有 dsh 私有根
+# `<project>/.dsh/skills` 与 `~/.dsh/skills`；四者一并扫，与 dsh 侧技能面板看到的一致。
+# `builtin_assets` 的清单校验与本表判 `family`，落点取各元组首个目录。
+SKILL_DIRS_BY_FAMILY = {
+    "dsh_plugin": (("~/.dsh/skills", "~/.agents/skills"),
+                   (".dsh/skills", ".agents/skills")),
+}
+# SKILL.md 相对扫描根的最大目录深度：2 层（分类/技能名，如 <类>/<名>/SKILL.md）
+SKILL_WALK_MAX_DEPTH = 2
+# SKILL.md frontmatter 的 name/description 行解析（简单 key: value，足够通用格式）
+_SKILL_FRONT_RE = re.compile(r"\A---\s*\n(.*?)\n---", re.S)
+_SKILL_NAME_RE = re.compile(r"^name:[ \t]*(.+)$", re.M)
+_SKILL_DESC_RE = re.compile(r"^description:[ \t]*(.+)$", re.M)
+# description 截断长度（避免超长描述撑爆下拉）
+_SKILL_DESC_LIMIT = 200
+
+
+def _parse_skill_md(path, fallback_name):
+    """解析一个 SKILL.md 的 frontmatter，返回 (name, description)。
+
+    name 缺省用所在目录名；description 缺省空串（截断到 _SKILL_DESC_LIMIT）；
+    文件读失败返回 None，调用方跳过该条。
+    """
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            head = f.read(4096)
+    except OSError:
+        return None
+    m = _SKILL_FRONT_RE.match(head)
+    body = m.group(1) if m else head  # 无 frontmatter 时退化为头部全文（容错）
+    nm = _SKILL_NAME_RE.search(body)
+    dm = _SKILL_DESC_RE.search(body)
+    return (nm.group(1).strip() if nm else fallback_name,
+            dm.group(1).strip()[:_SKILL_DESC_LIMIT] if dm else "")
+
+
+def _scan_skill_dir(root, source):
+    """扫描一个 skill 根目录（深度受限），返回 [{name, description, source}]。
+
+    目录不存在/不可读返回空列表；深度按相对根的目录层数限制
+    （SKILL.md 最深位于第 SKILL_WALK_MAX_DEPTH 层）。
+    """
+    skills = []
+    if not root or not os.path.isdir(root):
+        return skills
+    base_depth = root.rstrip(os.sep).count(os.sep)
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel = dirpath.rstrip(os.sep).count(os.sep) - base_depth
+        # 只在深度未达上限前继续下钻（SKILL.md 允许出现在 rel <= MAX_DEPTH 层）
+        dirnames[:] = [d for d in dirnames if rel < SKILL_WALK_MAX_DEPTH]
+        if "SKILL.md" not in filenames:
+            continue
+        parsed = _parse_skill_md(os.path.join(dirpath, "SKILL.md"),
+                                 os.path.basename(dirpath.rstrip(os.sep)))
+        if parsed:
+            skills.append({"name": parsed[0], "description": parsed[1],
+                           "source": source})
+    return skills
+
+
+def scan_skills(agent_path, project_dir=""):
+    """列出指定 agent CLI 可用的 skill（用户级 + 项目级），供项目能力下拉。
+
+    目录约定见 SKILL_DIRS_BY_FAMILY（dsh 插件族四目录）；同名 skill 项目级覆盖
+    用户级；agent_path 为空（未配置）返回空列表，无目录约定的族返回空。
+    返回 [{name, description, source}]，按 name 排序；纯文件扫描不做缓存。
+    """
+    ap = (agent_path or "").strip()
+    if not ap:
+        return []
+    family = agent_family(ap)
+    user_dirs, proj_dirs = SKILL_DIRS_BY_FAMILY.get(family, ((), ()))
+    found = {}
+    for d in user_dirs:
+        for s in _scan_skill_dir(os.path.expanduser(d), "user"):
+            found.setdefault(s["name"], s)
+    pd = (project_dir or "").strip()
+    if pd:
+        for d in proj_dirs:
+            for s in _scan_skill_dir(os.path.join(pd, d), "project"):
+                found[s["name"]] = s  # 项目级覆盖用户级
+    return sorted(found.values(), key=lambda s: s["name"])

package/auth.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Touchstone 认证：PBKDF2 密码哈希、session 签发与校验、登录限流。
+
+纯标准库。db 层会话表由 server.py 组装调用（本模块不依赖 db.py）。
+"""
+
+import hashlib
+import hmac
+import os
+import secrets
+import threading
+import time
+
+PBKDF2_ITER = 100_000
+SESSION_TTL = 7 * 24 * 3600  # 7 天
+COOKIE_NAME = "ts_session"
+
+
+def hash_password(password):
+    """返回 (哈希 hex, 盐 hex)。PBKDF2-HMAC-SHA256，10 万轮，16 字节随机盐。
+
+    仅用于种子 admin 等存量账号；新写入的密码统一用 md5_password（见下）。
+    """
+    salt = os.urandom(16)
+    digest = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, PBKDF2_ITER)
+    return digest.hex(), salt.hex()
+
+
+def md5_password(password):
+    """返回 (MD5 hex, 盐空串)。
+
+    按需求约定：注册用户/后台重置/修改密码统一用 MD5 存储（无盐）。仅 32 位 hex。
+    """
+    return hashlib.md5(password.encode("utf-8")).hexdigest(), ""
+
+
+def verify_password(password, pass_hash, salt_hex):
+    """常量时间比对，防时序侧信道。
+
+    兼容两种存量格式：长度为 32 的 hex 按 MD5 验证（新注册/重置的密码），
+    否则按 PBKDF2（种子 admin 等旧账号）。
+    密码非字符串（如 JSON null）直接判不匹配，不抛异常。
+    """
+    if not isinstance(password, str):
+        return False
+    if len(pass_hash) == 32:
+        return hmac.compare_digest(md5_password(password)[0], pass_hash)
+    try:
+        digest = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"),
+                                     bytes.fromhex(salt_hex), PBKDF2_ITER)
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(digest.hex(), pass_hash)
+
+
+def new_token():
+    """新会话 token（32 字节随机 hex）。"""
+    return secrets.token_hex(32)
+
+
+def session_expiry():
+    """会话过期时间字符串（now + 7 天）。"""
+    return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(time.time() + SESSION_TTL))
+
+
+class LoginLimiter:
+    """每 IP 每分钟最多 10 次登录尝试的滑动窗口限流（内存态即可）。"""
+
+    def __init__(self, max_attempts=10, window=60):
+        self.max_attempts = max_attempts
+        self.window = window
+        self._lock = threading.Lock()
+        self._records = {}  # ip -> [尝试时间戳]
+
+    def allow(self, ip):
+        """返回 True 表示本次尝试放行（尝试计数在 check 后须调用 record）。"""
+        now = time.time()
+        with self._lock:
+            records = [t for t in self._records.get(ip, []) if now - t < self.window]
+            self._records[ip] = records
+            return len(records) < self.max_attempts
+
+    def record(self, ip):
+        with self._lock:
+            self._records.setdefault(ip, []).append(time.time())
+