@henlii/pidance 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 agegr
+Copyright (c) 2026 Henry Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,151 @@
+<div align="center">
+  <img src="./docs/assets/pidance-banner.png" alt="Pidance — Move with Pi" width="760">
+  <p><strong>Let Pi sessions, tools, and project workflows move naturally in the browser.</strong></p>
+  <p>
+    <a href="./README.md">简体中文</a> ·
+    <a href="https://github.com/henlii/pidance/issues">Issues</a> ·
+    <a href="./docs/release.md">Release guide</a>
+  </p>
+</div>
+
+Pidance is an open-source web client for the [Pi](https://github.com/badlogic/pi-mono) coding agent. It reads local Pi session files directly and preserves Pi SDK session and runtime semantics, bringing live chat, project files, Git, worktrees, subagents, and configuration into one browser workspace. Pi remains the source of truth for data and execution semantics; Pidance provides a clearer and more complete interface.
+
+> Current version: `0.1.0` · npm package: `@henlii/pidance` · CLI: `pidance`
+
+## Preview
+
+![Pidance new-session workspace](./docs/screenshots/desktop.png)
+
+<p align="center"><sub>New-session workspace with project and worktree selectors, model controls, and contextual side panels. The path shown is anonymized.</sub></p>
+
+![Pidance appearance settings](./docs/screenshots/settings.png)
+
+<p align="center"><sub>Appearance settings with Light, Dark, System, Chamber, and Fusion options.</sub></p>
+
+## Features
+
+- **Project-oriented sessions**: browse a Project → Worktree → Session tree with search, recent sessions, archive/restore, rename, automatic titles, and HTML export.
+- **Live agent chat**: stream responses, thinking, tool calls, ANSI terminal output, compaction, and running state over SSE, with reconciliation after reconnects.
+- **Safe exploration**: continue from an earlier message, create an in-session branch, or fork to an independent `.jsonl` session without conflating those semantics.
+- **Project workspace**: browse and preview source, Markdown, images, audio, PDFs, and DOCX; search files, use `@` mentions, and inspect Git status and diffs.
+- **Git worktree workflow**: select, create, and remove worktrees in the UI while new sessions and the file workspace follow the chosen checkout.
+- **Pi ecosystem integration**: inspect synchronous and asynchronous subagent run status, interact with generic extension UI cards, and view read-only projections of structured todos.
+- **Central configuration**: manage provider authentication, API keys, models and model tests, session defaults, skills, plugins, and project trust.
+- **Polished interface**: responsive desktop/mobile layouts, a command palette, session minimap, completion sound, English and Chinese, plus Light / Dark / System themes.
+- **Explicit security boundaries**: project file allowlists, path and symlink checks, Host and CSRF guards, and mandatory passwords for non-loopback listeners.
+
+## Quick start
+
+Node.js `>= 20.9.0` is required.
+
+### Run without installing
+
+```bash
+npx @henlii/pidance@latest
+```
+
+### Install globally
+
+```bash
+npm install -g @henlii/pidance
+pidance
+```
+
+Open [http://localhost:31415](http://localhost:31415) when the server is ready. The CLI attempts to open the browser by default.
+
+```bash
+pidance --port 8080
+pidance --hostname 127.0.0.1
+pidance -p 8080 -H 127.0.0.1
+pidance --no-open
+```
+
+`PORT` and `PIDANCE_NO_OPEN=1` are also supported. Pidance reads `~/.pi/agent` by default; set `PI_CODING_AGENT_DIR` to use another Pi agent directory.
+
+### Remote or LAN access
+
+Listening on `0.0.0.0`, `::`, a LAN address, or another non-loopback host requires a password. The CLI refuses to start without one:
+
+```bash
+PIDANCE_PASSWORD='use-a-strong-password' pidance --hostname 0.0.0.0
+```
+
+For local-only use, bind explicitly to `127.0.0.1`. The legacy `PI_WEB_PASSWORD` variable remains compatible; new deployments should prefer `PIDANCE_PASSWORD`.
+
+### HTTP proxy
+
+Server-side model and API requests honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:7890 \
+NO_PROXY=localhost,127.0.0.1 \
+pidance
+```
+
+## Development and testing
+
+```bash
+npm install
+npm run dev       # http://localhost:31415
+npm run check     # typecheck + lint + unit tests
+```
+
+Additional acceptance checks:
+
+```bash
+npm run verify:render-bridge  # real pi-subagents rendering bridge
+npm run test:browser          # browser regression against 31416 by default
+```
+
+Do **not** run `npm run build` or `next build` during everyday development: it writes to `.next/` and can disrupt the development server. Production builds belong in an isolated release checkout through `npm run release:check`.
+
+### Continuous test deployment (31416)
+
+After application code changes, deploy the current workspace to the isolated production-mode test service:
+
+```bash
+node .agents/skills/pidance-development/scripts/local-deploy.mjs restart
+```
+
+| Port | Purpose |
+| --- | --- |
+| **31415** | Pidance product default: CLI, stable installation, `npm run dev` / `npm start` |
+| **31416** | Continuous workspace test build in isolated `.next-public`; never public-proxied |
+| **30141** | Upstream pi-web; this repository never operates it |
+
+## Release process
+
+Formal releases use a two-stage audit gate: run checks and the build in an isolated checkout, audit the prospective package, explicitly create the tgz, and then audit the real archive. Only that same accepted tgz may be used for installation smoke tests, npm, and the GitHub Release. No script automatically changes versions, creates tags, pushes, or publishes.
+
+See [docs/release.md](./docs/release.md) for the complete procedure.
+
+## Architecture
+
+```text
+Browser
+  ├─ Session / file / Git REST APIs ─▶ Next.js Route Handlers ─▶ local disk and Pi config
+  ├─ Send message ───────────────────▶ SessionService ──────────▶ AgentSession
+  └─ SSE events ◀──────────────────── EventStreamManager ◀───── AgentSession events
+
+~/.pi/agent/sessions/*.jsonl always remains the session source of truth
+```
+
+- **Read-only browsing** parses Pi `.jsonl` sessions without creating an AgentSession.
+- **Sending a message** creates or reuses an in-process AgentSession wrapper on the server.
+- Session service, event streaming, extension UI, project context, and chat composition form one-way seams so the UI cannot bypass session lifecycle rules.
+- File endpoints only expose explicit roots such as selected projects, worktrees, and session working directories.
+
+## Documentation
+
+- [Git worktrees](./docs/worktrees.md)
+- [Release and package auditing](./docs/release.md)
+- [Interface design system](./docs/ui-redesign/README.md)
+- [Theme tokens](./docs/ui-redesign/theme-tokens.md)
+- [Chat architecture refactor](./docs/chat-refactor-plan.md)
+- [OpenChamber upgrade evaluation](./docs/openchamber-upgrade-evaluation-2026-08-05.md)
+
+## Upstream and license
+
+Pidance is derived from [agegr/pi-web](https://github.com/agegr/pi-web) and is built around the session and runtime semantics of [badlogic/pi-mono](https://github.com/badlogic/pi-mono). Many thanks to both upstream projects and their contributors.
+
+Pidance is available under the [MIT License](./LICENSE). Upstream and derivative-work notices are retained in LICENSE: Copyright © 2026 agegr; Copyright © 2026 Henry Li.

package/README.md

@@ -0,0 +1,151 @@
+<div align="center">
+  <img src="./docs/assets/pidance-banner.png" alt="Pidance — Move with Pi" width="760">
+  <p><strong>让 Pi 的会话、工具与项目工作流在浏览器里自然舞动。</strong></p>
+  <p>
+    <a href="./README.en.md">English</a> ·
+    <a href="https://github.com/henlii/pidance/issues">问题反馈</a> ·
+    <a href="./docs/release.md">发布说明</a>
+  </p>
+</div>
+
+Pidance 是面向 [Pi](https://github.com/badlogic/pi-mono) coding agent 的开源 Web 客户端。它直接读取本机 Pi 会话文件，并沿用 Pi SDK 的会话与运行时语义，把实时对话、项目文件、Git、工作树、子代理和配置管理汇集到一个浏览器工作区。Pi 仍是数据与执行语义的事实来源；Pidance 负责提供更清晰、更完整的操作界面。
+
+> 当前版本：`0.1.0` · npm 包：`@henlii/pidance` · CLI：`pidance`
+
+## 界面预览
+
+![Pidance 新会话工作区](./docs/screenshots/desktop.png)
+
+<p align="center"><sub>新会话工作区：项目与工作树选择、模型、思考等级和右侧上下文面板。截图中的路径已脱敏。</sub></p>
+
+![Pidance 外观设置](./docs/screenshots/settings.png)
+
+<p align="center"><sub>外观设置：浅色、深色、跟随系统，以及 Chamber / Fusion 两套主题风格。</sub></p>
+
+## 功能特性
+
+- **项目化会话空间**：按 Project → Worktree → Session 浏览会话树，支持搜索、最近会话、归档、恢复、重命名、自动命名与 HTML 导出。
+- **实时 Agent 对话**：通过 SSE 呈现流式回复、思考过程、工具调用、终端 ANSI 输出、压缩状态和运行中状态；页面恢复后自动对账。
+- **安全探索不同方向**：从历史消息继续、创建会话内分支，或 fork 为独立 `.jsonl` 会话；两种分支语义清晰分离。
+- **项目工作区**：浏览与预览源码、Markdown、图片、音频、PDF 和 DOCX，支持文件搜索、`@` 引用、Git 状态与 diff。
+- **Git worktree 工作流**：在界面内选择、创建和移除工作树，新会话与文件工作区自动跟随所选 checkout。
+- **Pi 生态集成**：展示同步与异步子代理运行状态、通用扩展 UI 卡片与交互，以及结构化 Todos 的只读投影。
+- **集中配置**：管理供应商认证、API Key、模型与测试、会话默认值、技能、插件和项目信任。
+- **精心打磨的界面**：响应式桌面/移动布局、命令面板、会话 minimap、完成提示音、中英双语，以及 Light / Dark / System 主题。
+- **边界明确的安全设计**：项目文件 allow-list、路径与符号链接检查、Host/CSRF 防护；非回环监听必须配置密码。
+
+## 快速开始
+
+需要 Node.js `>= 20.9.0`。
+
+### 无需安装
+
+```bash
+npx @henlii/pidance@latest
+```
+
+### 全局安装
+
+```bash
+npm install -g @henlii/pidance
+pidance
+```
+
+服务就绪后访问 [http://localhost:31415](http://localhost:31415)。CLI 默认会尝试打开浏览器。
+
+```bash
+pidance --port 8080
+pidance --hostname 127.0.0.1
+pidance -p 8080 -H 127.0.0.1
+pidance --no-open
+```
+
+也可使用 `PORT` 与 `PIDANCE_NO_OPEN=1`。Pidance 默认读取 `~/.pi/agent`；可通过 `PI_CODING_AGENT_DIR` 指向其他 Pi agent 目录。
+
+### 远程或局域网访问
+
+绑定 `0.0.0.0`、`::`、局域网 IP 或其他非回环地址时，必须设置认证密码，否则 CLI 会拒绝启动：
+
+```bash
+PIDANCE_PASSWORD='请使用强密码' pidance --hostname 0.0.0.0
+```
+
+仅本机访问时建议显式绑定 `127.0.0.1`。兼容旧变量 `PI_WEB_PASSWORD`，新部署优先使用 `PIDANCE_PASSWORD`。
+
+### HTTP 代理
+
+服务端模型与 API 请求读取标准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`：
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:7890 \
+NO_PROXY=localhost,127.0.0.1 \
+pidance
+```
+
+## 开发与测试
+
+```bash
+npm install
+npm run dev       # http://localhost:31415
+npm run check     # typecheck + lint + 单元测试
+```
+
+其他验收入口：
+
+```bash
+npm run verify:render-bridge  # 真实 pi-subagents 渲染桥
+npm run test:browser          # 浏览器回归，默认访问 31416
+```
+
+日常开发**不要**执行 `npm run build` 或 `next build`：它会写入 `.next/` 并干扰开发服务。正式构建只在隔离发布 checkout 中通过 `npm run release:check` 执行。
+
+### 持续测试部署（31416）
+
+每次应用代码修改完成后，将当前工作区部署到隔离的生产模式测试服务：
+
+```bash
+node .agents/skills/pidance-development/scripts/local-deploy.mjs restart
+```
+
+| 端口 | 用途 |
+| --- | --- |
+| **31415** | Pidance 产品默认：CLI、稳定安装版、`npm run dev` / `npm start` |
+| **31416** | 当前工作区持续测试版：`.next-public` 隔离生产构建，不对外反代 |
+| **30141** | 上游 pi-web；本仓绝不操作 |
+
+## 发布
+
+正式发布采用“双审计”门禁：隔离 checkout 中完成质量检查与构建，生成前审计包清单和内容，显式 `npm pack`，再审计真实 tgz；同一份已验收 tgz 才能用于安装冒烟、npm 与 GitHub Release。脚本不会自动改版本、打 tag、push 或 publish。
+
+完整步骤见 [docs/release.md](./docs/release.md)。
+
+## 架构概览
+
+```text
+浏览器
+  ├─ 会话 / 文件 / Git REST API ──▶ Next.js Route Handlers ──▶ 本地磁盘与 Pi 配置
+  ├─ 发送消息 ───────────────────▶ SessionService ───────────▶ AgentSession
+  └─ SSE 事件流 ◀──────────────── EventStreamManager ◀────── AgentSession 事件
+
+~/.pi/agent/sessions/*.jsonl 始终是会话事实来源
+```
+
+- **只读浏览**直接解析 Pi `.jsonl` 会话，不创建 AgentSession。
+- **发送消息**时才在服务端进程内创建或复用 AgentSession wrapper。
+- 会话服务、事件流、扩展 UI、项目上下文和聊天合成器按单向 seam 分层，避免 UI 绕过会话生命周期。
+- 文件端点仅允许访问已选择项目、工作树和会话工作目录等明确根路径。
+
+## 文档
+
+- [Git worktree 使用说明](./docs/worktrees.zh-CN.md)
+- [发布与制品审计](./docs/release.md)
+- [界面设计与主题规范](./docs/ui-redesign/README.md)
+- [主题 Token](./docs/ui-redesign/theme-tokens.md)
+- [会话系统重构说明](./docs/chat-refactor-plan.md)
+- [OpenChamber 升级评估](./docs/openchamber-upgrade-evaluation-2026-08-05.md)
+
+## 上游与许可
+
+Pidance 源自 [agegr/pi-web](https://github.com/agegr/pi-web)，并围绕 [badlogic/pi-mono](https://github.com/badlogic/pi-mono) 的会话与运行时语义构建。感谢两个上游项目及其贡献者。
+
+本项目采用 [MIT License](./LICENSE)。上游版权与派生作品声明保留于 LICENSE：Copyright © 2026 agegr；Copyright © 2026 Henry Li。

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+# Pidance
+
+[English](./README.md)
+
+![Pidance 横幅](https://raw.githubusercontent.com/henlii/pidance/main/docs/assets/pidance-banner.png)
+
+Pidance 是基于 [Pi](https://github.com/badlogic/pi-mono) 的统一 Agent 工作空间上层客户端。它不脱离 Pi，而是读取本机 Pi 会话文件并遵循 Pi 的运行时语义，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
+
+![Pidance 样例数据产品预览：会话侧边栏、带工具卡片的对话区和文件工作区](https://raw.githubusercontent.com/henlii/pidance/main/docs/assets/pidance-preview.png)
+
+*样例数据产品预览：会话侧边栏、包含工具卡片的对话区与文件工作区。图中内容均为示意样例数据，并非真实运行会话。*
+
+## 路线图
+
+路线图、实施进度和验收标准统一记录在各阶段 tracking Issue 中：
+
+- [第一阶段：架构 seam 与 OpenChamber 风格产品改造](https://github.com/henlii/pidance/issues/1)
+- [第二阶段：补齐 Pi 生态高价值盲区（待办镜像、会话全文搜索、subagent 结果卡片、项目信任）](https://github.com/henlii/pidance/issues/2)
+- [第三阶段：Pi 扩展生态可观测性与 Agent 默认值设置](https://github.com/henlii/pidance/issues/3)
+- [第四阶段：辅助信息面与低频能力（统计、结果浏览、克隆、模板、版本）](https://github.com/henlii/pidance/issues/4)
+
+## Upstream / 上游来源
+
+Pidance 源自 [agegr/pi-web](https://github.com/agegr/pi-web)，遵循 MIT License；底层运行时来自 [badlogic/pi-mono](https://github.com/badlogic/pi-mono)。项目保留 Pi 的会话文件格式与运行时语义，现有 Pi 数据仍是事实来源。上游版权和派生作品说明保留在 [LICENSE](./LICENSE) 中。
+
+## 快速开始
+
+**无需安装，直接运行：**
+
+```bash
+npx @henlii/pidance@latest
+```
+
+**或全局安装后使用：**
+
+```bash
+npm install -g @henlii/pidance
+pidance
+```
+
+启动后打开 [http://localhost:31415](http://localhost:31415)。命令行版本会在服务就绪后尝试自动打开浏览器。
+
+**可选参数：**
+
+```bash
+pidance --port 8080              # 自定义端口
+pidance --hostname 127.0.0.1     # 仅本机访问
+pidance -p 8080 -H 127.0.0.1     # 组合使用
+pidance --no-open                # 不自动打开浏览器
+
+PORT=8080 pidance                # 也支持环境变量
+PIDANCE_NO_OPEN=1 pidance        # 不自动打开浏览器（适用于后台服务或开机自启）
+```
+
+## HTTP 代理
+
+Pidance 的服务端模型请求和 API 请求会读取标准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。
+
+macOS 或 Linux：
+
+```bash
+HTTP_PROXY=http://127.0.0.1:7890 \
+HTTPS_PROXY=http://127.0.0.1:7890 \
+NO_PROXY=localhost,127.0.0.1 \
+npx @henlii/pidance@latest
+```
+
+Windows PowerShell：
+
+```powershell
+$env:HTTP_PROXY = "http://127.0.0.1:7890"
+$env:HTTPS_PROXY = "http://127.0.0.1:7890"
+$env:NO_PROXY = "localhost,127.0.0.1"
+npx @henlii/pidance@latest
+```
+
+## 功能介绍
+
+- **把历史工作接回来**：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
+- **放心试不同方向**：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
+- **跨分支工作**：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
+- **边聊边看项目文件**：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
+- **随时掌握会话状态**：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
+- **少离开当前界面**：模型、登录/API key、模型测试和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
+
+## 注意事项
+
+- **数据目录**：默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **会话文件**：路径形如 `~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`。
+- **模型配置**：Models 面板读写 pi agent 目录下的 `models.json`，模型列表和默认模型由 pi 的配置解析得到。
+- **文件访问**：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
+- **Git worktree**：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 [Pidance 里的 Worktree](./docs/worktrees.zh-CN.md)。
+- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；“Edit from here” 是同一会话文件里的分支。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+本地开发端口为 [http://localhost:31415](http://localhost:31415)（Pidance 产品默认；`30141` 留给上游 pi-web）。
+
+| 端口 | 角色 |
+|------|------|
+| **31415** | 产品默认（`npm run dev` / `npm start` / CLI `pidance`） |
+| **31416** | 持续本地测试部署（`local-deploy.mjs`，Next dev，不对公网） |
+| **30141** | 上游 pi-web / 既有服务 — 禁止操作 |
+
+常用检查：
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+开发时不要运行 `next build` / `npm run build`，它会写入 `.next/`，容易影响正在运行的 dev server。发布流程再执行构建。
+
+## 项目结构
+
+```
+app/
+  api/
+    agent/          # 创建/驱动 AgentSession，提供 SSE 事件流和 bash 输出
+    auth/           # OAuth 和 API key 管理
+    cwd/validate/   # 自定义工作目录校验
+    default-cwd/    # 获取 pi 默认工作目录
+    files/          # 文件列表、读取、预览、搜索、上传和 watch
+    file-index/     # 项目文件索引和 @ 提及搜索
+    git/            # 当前项目的 Git diff 和 status
+    home/           # 当前用户 home 目录
+    models/         # 可用模型、默认模型、thinking levels
+    models-config/  # 读写 models.json、测试模型
+    plugins/        # package 插件管理
+    sessions/       # 会话读取、重命名、自动命名、删除、上下文、状态、延迟 thinking 和 HTML 导出
+    skills/         # skills 列表、搜索、安装、更新、检查和启停
+    worktrees/      # Git worktree 列表、新建和删除
+components/
+  AppShell.tsx        # 主布局、URL 状态、顶部面板、文件标签
+  SessionSidebar.tsx  # 项目选择、会话树、Explorer
+  ChatWindow.tsx      # 消息区、SSE、拖拽图片、minimap
+  ChatInput.tsx       # 输入栏、模型/工具/thinking/compact/slash controls
+  MessageView.tsx     # 消息、thinking、tool call/result 渲染
+  ModelsConfig.tsx    # 模型和认证配置面板
+  SkillsConfig.tsx    # 技能管理面板
+  FileExplorer.tsx    # 文件树
+  FileViewer.tsx      # 源码、diff、图片、音频、PDF、DOCX 预览
+lib/
+  api-types.ts       # API 请求和响应的共享类型
+  ansi.ts             # 终端输出的 ANSI 转义序列处理
+  bash-output.ts      # bash 命令输出的格式化和解析
+  custom-ui-terminal.ts # 自定义 UI 输出的终端适配器
+  git-changes.ts      # Git diff/变更收集
+  git-status.ts       # Git status 收集和规范化
+  git-types.ts        # Git 数据共享类型
+  http-dispatcher.ts  # 服务端 fetch 的 HTTP(S) 代理配置
+  rpc-manager.ts      # AgentSessionWrapper 生命周期和全局 registry
+  session-reader.ts   # 解析 .jsonl 会话文件和分支上下文
+  session-file-references.ts # 会话引用文件的检查
+  normalize.ts        # 规范化 toolCall 字段名
+  file-access.ts      # 文件读取安全边界和允许的根目录
+  file-fuzzy.ts       # 文件模糊搜索工具
+  file-upload.ts      # 文件上传校验和冲突处理
+  file-paths.ts       # 文件路径编码/相对路径工具
+  models-cache.ts     # 模型列表和默认值缓存
+  session-title.ts    # 会话标题和自动命名工具
+  skill-updates.ts    # 技能更新操作
+  skill-lock.ts       # 技能更新锁
+  terminal-input.ts   # 终端输入处理
+  worktree.ts         # 项目/worktree 解析和 Git 操作
+  markdown.ts         # Markdown/Mermaid/KaTeX 插件配置
+  pi-types.ts         # pi 相关类型
+hooks/
+  useAgentSession.ts  # 会话加载、发送命令、SSE 状态机
+  useAudio.ts         # 完成提示音
+  useDragDrop.ts      # 图片拖拽
+  useKeyboardShortcuts.ts # 键盘快捷键处理
+  useTheme.ts         # 主题切换
+bin/
+  pidance.js          # npm CLI 入口（仅 pidance；pi-web 归上游）
+instrumentation.ts    # 初始化服务端 HTTP dispatcher
+```