[codex] Complete Xiaoan desktop productization readiness

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug Report
-about: 报告一个问题
+about: 报告小安桌面端的问题
 title: "[Bug] "
 labels: bug
 assignees: ""
@@ -9,7 +9,8 @@ assignees: ""
 **环境信息**
 - OS:
 - Node.js 版本:
-- HanaAgent 版本:
+- 小安版本 / commit:
+- 数据目录：`~/.xiaoan` / `XIAOAN_HOME` / legacy `~/.hanako`
 
 **问题描述**
 简明描述遇到的问题。
@@ -25,3 +26,8 @@ assignees: ""
 
 **日志 / 截图**
 如有相关日志或截图请贴出。
+
+**已尝试**
+- [ ] 重启小安
+- [ ] 使用开发数据目录复现
+- [ ] 查看终端或 diagnostics 日志

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 维护计划
+    url: https://github.com/An-an-525/An-Agent/blob/main/docs/PROJECT-MAINTENANCE-PLAN.md
+    about: 查看当前 PR 拆分、合并门禁和维护队列。

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
 name: Feature Request
-about: 提一个新功能建议
+about: 提一个小安产品能力建议
 title: "[Feature] "
 labels: enhancement
 assignees: ""
@@ -12,5 +12,13 @@ assignees: ""
 **使用场景**
 这个功能解决什么问题？在什么场景下会用到？
 
+**用户路径**
+用户第一次看到它时，应该从哪里进入？需要哪些默认状态？
+
+**边界**
+- [ ] 不需要替换 Pi SDK
+- [ ] 不需要自研 agent loop
+- [ ] 不破坏 legacy 数据读取
+
 **可能的实现方式**
-如果有想法，描述一下可能的实现路径。
+如果有想法，描述一下可能的实现路径；没有也可以留空。

.github/pull_request_template.md

@@ -0,0 +1,55 @@
+## Summary
+
+-
+
+<!-- Lead with the Xiaoan user/product outcome. Put upstream or open-source credits in References, not in the first screen. -->
+
+## Layer
+
+- [ ] L5 product / docs / copy
+- [ ] L4 desktop / server / hub shell
+- [ ] L3 core domain
+- [ ] L2 lib / shared
+- [ ] L0 Pi SDK
+
+## Change Type
+
+- [ ] Xiaoan product copy / brand
+- [ ] Runtime migration / config
+- [ ] UI layout / theme / motion
+- [ ] Provider / model defaults
+- [ ] Plugin / capability
+- [ ] Bug fix
+- [ ] Tests only
+- [ ] Docs only
+
+## Guardrails
+
+- [ ] No Pi SDK replacement or custom agent loop
+- [ ] No unrelated refactor bundled in
+- [ ] Legacy compatibility preserved where relevant
+- [ ] User/provider config is not overwritten
+- [ ] User-visible copy avoids upstream/framework terms unless intentionally internal
+- [ ] Docs updated or not needed
+
+## Verification
+
+- [ ] `npm run typecheck`
+- [ ] `npm run dep:check` if cross-layer imports changed
+- [ ] Relevant focused tests:
+
+```text
+
+```
+
+- [ ] Full `npm test` for large/release-bound batches
+- [ ] Desktop smoke/manual check if UI changed
+
+## Risk / Rollback
+
+- Risk:
+- Rollback:
+
+## References / Credits
+
+- Open-source projects or upstream changes referenced:

.gitignore

@@ -1,5 +1,5 @@
 # ═══════════════════════════════════════════
-# 用户数据（已迁移到 ~/.hanako/）
+# 用户数据（canonical ~/.xiaoan/；legacy ~/.hanako/ 双读）
 # ═══════════════════════════════════════════
 agents/
 user/
@@ -61,6 +61,7 @@ CLAUDE.md
 # 临时文件
 tmp/
 test-results/
+.vitest-results*.json
 __pycache__/
 *.pyc
 /index.html

.nvmrc

@@ -0,0 +1 @@
+24

CONTRIBUTING.md

@@ -1,24 +1,26 @@
-# Contributing to 小安 Agent（An-Agent）
+# Contributing to 小安（Xiaoan）
 
 感谢参与 **[An-an-525/An-Agent](https://github.com/An-an-525/An-Agent)** 的主线维护。
 
-本仓库是基于 [OpenHanako](https://github.com/liliMozi/openhanako) 的 **独立 fork**，不是上游官方仓库。贡献前请先读 [docs/README.md](./docs/README.md) 了解文档结构。
+本仓库维护的是 **小安桌面 AI 助手**。贡献前请先读 [docs/README.md](./docs/README.md) 了解文档结构；技术来源与开源参考放在文末说明，不要在 GitHub 标题、PR 标题和首屏描述里先讲上游项目。
 
 ---
 
 ## 1. 贡献前先理解
 
 | 问题 | 答案 |
 |------|------|
-| 这是什么？ | 通用桌面个人 Agent（左聊右看），品牌「小安 / Xiaoan」 |
-| 底座能换吗？ | **不能** — 运行时 OpenHanako + Pi SDK |
+| 这是什么？ | 开箱即用的桌面 AI 助手（左聊右看），品牌「小安 / Xiaoan」 |
+| 底座能换吗？ | **不能** — 保持现有桌面壳与 Pi SDK 底座 |
 | 主要改哪里？ | `plugins/xiaoan-core`、`desktop/` 定制 UI、`shared/xiaoan-*`、`docs/` |
 | 什么不做？ | PPT 生成线、自研 agent loop、fork Pi 内核 |
 | 工程原则？ | 不换底座 → 最小 diff → 分层改动 → 可验证 → 可合并上游 |
 | 如何系统性内化？ | [docs/XIAOAN-CODEBASE-INTERNALIZATION.md](./docs/XIAOAN-CODEBASE-INTERNALIZATION.md) + `npm run dep:check` |
 
 详细方法论：[docs/XIAOAN-ENGINEERING-METHODOLOGY.md](./docs/XIAOAN-ENGINEERING-METHODOLOGY.md)
 
+当前大改动收口、PR 拆分和合并门禁见：[docs/PROJECT-MAINTENANCE-PLAN.md](./docs/PROJECT-MAINTENANCE-PLAN.md)。不要把多轮 Cursor/历史改动整包提交。
+
 ---
 
 ## 2. 开发环境
@@ -44,7 +46,7 @@ npm install
 ### 数据隔离（推荐）
 
 ```bash
-export HANA_HOME=~/.hanako-dev
+export XIAOAN_HOME=~/.xiaoan-dev
 ```
 
 ### 启动
@@ -68,13 +70,13 @@ npm start
 ```
 L4 产品/品牌/docs     shared/xiaoan-* · themes · design · locales
 L3 小安方法论         plugins/xiaoan-core · skills2set/xiaoan-handbook
-L2 OpenHanako 继承   server · core · hub · lib · 大部分 desktop/react
+L2 继承底座           server · core · hub · lib · 大部分 desktop/react
 L1 Pi SDK             lib/pi-sdk/（几乎不改）
 ```
 
 | 需求类型 | 首选路径 |
 |----------|----------|
-| 新 Agent 工具 | `plugins/xiaoan-core/tools/` |
+| 新小安能力工具 | `plugins/xiaoan-core/tools/` |
 | Brief / Plan 右栏 | `desktop/src/react/components/right-workspace/` |
 | 控制台排版 | `desktop/src/design/xiaoan-layout.css` |
 | 主题 / 品牌 | `desktop/src/themes/xiaoan-console*.css` |
@@ -104,6 +106,7 @@ npm run dep:check
 | 迁移 / first-run | `npm test -- tests/xiaoan-fork-migrate.test.ts` |
 | 聊天排版 | `npm test -- InputArea.layout` |
 | 主题 | `npm test -- tests/theme-registry.test.ts` |
+| 桌面 UI 契约（legacy theme / GSAP） | `npm test -- tests/xiaoan-layout-theme-contract.test.ts tests/xiaoan-gsap-chat-motion.test.ts` |
 
 UI 改动请在本地目测：`localStorage.setItem('xiaoan-theme','xiaoan-console'); location.reload()`
 
@@ -113,12 +116,18 @@ UI 改动请在本地目测：`localStorage.setItem('xiaoan-theme','xiaoan-conso
 
 ### Commit message
 
+GitHub 展示规则：
+
+- commit / PR 标题先讲小安结果，不用上游项目名开头。
+- 用户可见变更用“小安、能力、工作区、状态、连接”等产品语言。
+- 上游和开源来源放在 PR 末尾的 reference / credit，不放在 summary 第一屏。
+
 ```
 <type>(<scope>): <subject>
 
-feat(ui): add flex-footer layout for xiaoan-console
-fix(xiaoan-core): guard brief gaps to max 3
-docs: update layout system guide
+feat(ui): stabilize Xiaoan chat layout
+fix(runtime): preserve Xiaoan provider config during migration
+docs(github): align Xiaoan project presentation
 ```
 
 ### PR 描述建议包含
@@ -128,6 +137,8 @@ docs: update layout system guide
 - **Test plan**：跑过哪些命令、手动检查项
 - **Docs**：更新了哪些 `docs/` 文件
 
+GitHub 会自动使用 `.github/pull_request_template.md`。提交前按模板确认：单一意图、分层明确、legacy 兼容未破坏、相关测试已跑。
+
 ### 不要提交
 
 - `.env`、API Key、`~/.hanako` 用户数据
@@ -141,6 +152,8 @@ docs: update layout system guide
 
 - 新能力 → 对应 CODEMAP 专题 + [docs/README.md](./docs/README.md) 若需登记
 - 排版 → [docs/XIAOAN-LAYOUT.md](./docs/XIAOAN-LAYOUT.md)
+- 主题 / GSAP / 桌面 UI 规范 → [docs/XIAOAN-DESKTOP-UI-STANDARDS.md](./docs/XIAOAN-DESKTOP-UI-STANDARDS.md)
+- UI bug 事件记录 → [docs/incidents/](./docs/incidents/README.md)（黑曜石：`Obsidian/初始/99 - Agent指南与规范/An-Agent/`）
 - 维护流程 → [docs/MAINTAINER.md](./docs/MAINTAINER.md)
 
 ---
@@ -151,10 +164,10 @@ Issue 请包含：
 
 - OS 与版本
 - Node.js 版本
-- `HANA_HOME` 是否隔离
+- `XIAOAN_HOME` 是否隔离
 - 复现步骤
 - 期望 vs 实际
-- 相关日志（`~/.hanako-dev/diagnostics/` 或终端输出）
+- 相关日志（`~/.xiaoan-dev/diagnostics/`、legacy `~/.hanako-dev/diagnostics/` 或终端输出）
 
 ---
 
@@ -167,7 +180,7 @@ desktop/        Electron + React（含 xiaoan-console UI）
 hub/            调度、频道、bridge
 lib/            记忆、工具、沙盒
 plugins/        内置插件（xiaoan-core）
-skills2set/     内置 Skill（xiaoan-handbook）
+skills2set/     内置技能（xiaoan-handbook）
 shared/         schema、xiaoan-fork 元数据
 tests/          Vitest
 docs/           说明与工程方法论（从 docs/README.md 进入）
@@ -189,7 +202,9 @@ docs/           说明与工程方法论（从 docs/README.md 进入）
 | 文档 | 用途 |
 |------|------|
 | [docs/README.md](./docs/README.md) | 文档总索引 |
+| **黑曜石** `99 - Agent指南与规范/An-Agent/00-An-Agent-工程文档索引.md` | 维护者知识库（含全部代码地图镜像） |
+| `./scripts/sync-docs-to-obsidian.sh` | 将 docs/ 同步到黑曜石 |
 | [docs/XIAOAN-ENGINEERING-METHODOLOGY.md](./docs/XIAOAN-ENGINEERING-METHODOLOGY.md) | 工程方法论 |
 | [docs/MAINTAINER.md](./docs/MAINTAINER.md) | 维护者手册 |
-| [docs/HANAKO-INTERNALIZATION.md](./docs/HANAKO-INTERNALIZATION.md) | OpenHanako 内化 |
-| [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md) | Agent 方法论 |
+| [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md) | 小安方法论 |
+| [UPSTREAM-NOTICE.md](./UPSTREAM-NOTICE.md) | 技术来源与开源参考 |

README.md

@@ -1,8 +1,8 @@
-# 小安 Agent（Xiaoan）
+# 小安（Xiaoan）
 
 **主维护仓库**：[An-an-525/An-Agent](https://github.com/An-an-525/An-Agent) · 默认分支 `main` · 维护者 **An-an-525**
 
-基于 [OpenHanako](https://github.com/liliMozi/openhanako) fork 的通用桌面个人 Agent，运行时底座为 **Pi SDK**。本仓库是**独立产品线**的日常开发与发布入口，不接收上游 OpenHanako 自动更新。
+小安是开箱即用的桌面 AI 助手：左侧聊天，右侧查看资料和工作区，内置记忆、工具、能力扩展和书桌能力。用户打开应用看到的是完整的小安产品，而不是需要先配置的通用 AI 平台。
 
 > 不做 PPT 生成线。小安是左聊右看的 AI 副驾驶：对话、工具、记忆、书桌工作区。
 
@@ -12,31 +12,19 @@
 |---|---|
 | **Canonical 仓库** | `https://github.com/An-an-525/An-Agent` |
 | **开发分支** | `main`（已合并 xiaoan-console 排版与品牌化） |
-| **上游底座** | OpenHanako — 仅作源码参考，手动 merge/cherry-pick |
 | **配置真源** | `shared/xiaoan-fork.json` |
-| **本地数据** | 生产 `~/.hanako` · 开发 `HANA_HOME=~/.hanako-dev` |
+| **本地数据** | 生产 `~/.xiaoan`（legacy `~/.hanako` 双读）· 开发 `XIAOAN_HOME=~/.xiaoan-dev` |
 
 新功能、UI、文档、插件改动 **一律在本仓库 `main` 维护**；见 [docs/FORK-CONFIG.md](./docs/FORK-CONFIG.md)。
 
-## 与上游关系
-
-| 项 | 说明 |
-|---|---|
-| **上游** | [liliMozi/openhanako](https://github.com/liliMozi/openhanako)（Apache 2.0） |
-| **底座** | Pi coding-agent |
-| **定制** | `plugins/xiaoan-core/` — think / brief / ask + 默认「小安」Agent 模板 |
-| **设计文档** | `docs/agent-design/` |
-
-详见 [UPSTREAM-NOTICE.md](./UPSTREAM-NOTICE.md) 与 [docs/FORK-CONFIG.md](./docs/FORK-CONFIG.md)。
-
-**建议阅读顺序**： [docs/CODEMAP.md](./docs/CODEMAP.md)（导航）→ [docs/HANAKO-INTERNALIZATION.md](./docs/HANAKO-INTERNALIZATION.md)（内化底座）→ [docs/LOCAL-DEV.md](./docs/LOCAL-DEV.md)（跑起来）→ [docs/XIAOAN-LAYOUT.md](./docs/XIAOAN-LAYOUT.md)（控制台排版）→ [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md)（小安层）。
+**建议阅读顺序**： [docs/README.md](./docs/README.md)（文档中心）→ [docs/LOCAL-DEV.md](./docs/LOCAL-DEV.md)（跑起来）→ [docs/CODEMAP.md](./docs/CODEMAP.md)（导航）→ [docs/XIAOAN-LAYOUT.md](./docs/XIAOAN-LAYOUT.md)（控制台排版）→ [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md)（小安方法论）。
 
 **本地看桌面端** → [docs/LOCAL-DEV.md](./docs/LOCAL-DEV.md)
 
-## 功能（继承自 OpenHanako）
+## 功能
 
-- 记忆、人格、书桌（工作区）、多 Agent
-- Skills、插件、沙盒、Cron / 心跳
+- 记忆、人格、书桌（工作区）、小安的不同状态
+- 技能、能力扩展、沙盒、主动提醒与日常巡检
 - Electron + React 桌面端
 
 ## 开发
@@ -56,7 +44,7 @@ npm run typecheck
 - 品牌：小安 / Xiaoan（`xiaoan-console` 主题，樱花粉控制台 UI）
 - 排版：`desktop/src/design/xiaoan-layout.css` — 见 [docs/XIAOAN-LAYOUT.md](./docs/XIAOAN-LAYOUT.md)
 - 插件：`plugins/xiaoan-core/`（think / brief / ask / plan / confirm）
-- Agent 模板：新建助手时可选「小安」
+- 状态模板：新建助手时可选「小安」
 - 本地开发上下文包：[docs/XIAOAN-LOCAL-DEV-CONTEXT.md](./docs/XIAOAN-LOCAL-DEV-CONTEXT.md)
 
 ## 文档
@@ -70,7 +58,7 @@ npm run typecheck
 | 维护者 | [docs/MAINTAINER.md](./docs/MAINTAINER.md) · [docs/FORK-CONFIG.md](./docs/FORK-CONFIG.md) |
 | 代码地图 | [docs/CODEMAP.md](./docs/CODEMAP.md) |
 | 控制台排版 | [docs/XIAOAN-LAYOUT.md](./docs/XIAOAN-LAYOUT.md) |
-| Agent 方法论 | [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md) |
+| 小安方法论 | [docs/agent-design/XIAOAN-METHODOLOGY.md](./docs/agent-design/XIAOAN-METHODOLOGY.md) |
 | Cursor 上下文 | [docs/XIAOAN-LOCAL-DEV-CONTEXT.md](./docs/XIAOAN-LOCAL-DEV-CONTEXT.md) |
 
 ## 路线图
@@ -79,4 +67,8 @@ npm run typecheck
 
 ## 许可证
 
-应用主体遵循上游 **Apache License 2.0**。定制层与文档另附 MIT 说明见 `UPSTREAM-NOTICE.md`。
+应用主体遵循 **Apache License 2.0**。定制层与文档说明见 `UPSTREAM-NOTICE.md`。
+
+## 技术来源与开源参考
+
+小安站在成熟开源项目之上做产品化内化：桌面壳与基础能力参考 [OpenHanako](https://github.com/liliMozi/openhanako)，运行时底座为 Pi coding-agent。小安自己的默认体验、品牌、文案、配置、主题、工作区和方法论层在本仓库维护。详见 [UPSTREAM-NOTICE.md](./UPSTREAM-NOTICE.md) 与 [docs/FORK-CONFIG.md](./docs/FORK-CONFIG.md)。