@adongguo/yxdash 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adongguo
+
+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.md

@@ -0,0 +1,181 @@
+# yxdash
+
+> 终端里的云效工作项看板（命令名 `yxdash`）：缺陷 / 需求 / 迭代三视图，默认只看与我相关，链接可点击，自动刷新，同时是 Claude Code 等 agent 的结构化数据源。技术栈与 Claude Code 一致：TypeScript + React Ink 7 + Node ≥ 22（纯 ESM）。
+
+## 状态
+
+- ✅ 产品与方案调研（`docs/20260815-170653-云效TUI看板-产品与方案调研.md`）
+- ✅ 技术方案 v1.0（`docs/20260815-183843-yunxiao-tui技术方案.md`）
+- ✅ M1：缺陷/需求表格视图（自绘表格 + sections tab + 预览面板 + 键位全集 + YAML 配置 + 状态名动态解析 + 限流保护），替代 `/mybugs` `/mywork` 日常使用
+- ✅ M2 主体：迭代 master-detail 视图（需求默认三类全含、按阶段分组、`a` 按负责人过滤、`b` 缺陷开关、`g` 分组维度切换）
+- ✅ M3 提前项：`--json` / `--plain` 管道输出（agent / 脚本消费，含 sprint 视图）
+- ✅ M3 编辑能力：`e` 字段编辑（状态/负责人/优先级/严重程度，全 select 化）、`m` 状态流转直达、`d/c` 经 nvim($EDITOR) 编辑描述与新增评论、`C` 查看评论（详见 `docs/20260816-215451-M3编辑能力技术方案.md`）
+- ✅ M4：响应式布局（测量式列宽、断点行/卡片形态、长文本软换行，详见 `docs/20260818-202956-响应式布局技术方案.md`）
+- ✅ M5：迭代视图 vim 式分组折叠（空格 / `z` chord / `zs` solo，详见 `docs/20260819-105343-分组折叠vim化技术方案.md`）
+- ✅ M6：鼠标交互（滚轮滚动、单击选中/切换 section 与视图、双击预览、组头点击折叠；`ui.mouse: false` 或 `YXDASH_NO_MOUSE=1` 关闭，详见 `docs/20260820-000232-鼠标交互技术方案.md`）
+- ✅ M7：多选标记与批量复制（`v` 标记、`y`/`Y` 批量复制编号/链接、Esc 清除，详见 `docs/20260824-193458-多选复制与命令面板技术方案.md`）
+- ✅ M8：命令面板（`Ctrl+k` 唤起，中文/拼音/英文模糊搜索并执行任意操作，同一文档）
+- ⬜ M2 其余：`f` 过滤表单；M3 其余：多 profile
+
+## 安装与分发
+
+正式包名为 `@adongguo/yxdash`，安装后的命令名保持为 `yxdash`，通过公共 npm registry（npmjs）分发。此前的 `@adongguo/yunxiao-tui@0.1.1` 是旧品牌下的预览包；未加 scope 的 `yxdash` 因 npm 相似名称保护未曾发布。正式版从 `@adongguo/yxdash@1.0.1` 开始。
+
+联网安装无需额外 registry 配置：
+
+```bash
+npm install --global @adongguo/yxdash
+yxdash --version
+```
+
+也可以从 tag 流水线下载离线产物及 `SHA256SUMS`，校验后安装同一份已验证 tarball：
+
+```bash
+(cd release && shasum -a 256 -c SHA256SUMS)
+npm install --global ./release/yxdash-v1.0.1.tgz
+yxdash --help
+```
+
+tarball 会捆绑经锁文件验证的完整运行时依赖树，可在没有 registry 网络的环境中离线安装。自有 TypeScript 代码会先合并为单个 Node ESM 入口，再以固定 seed 做 minify 与混淆；公网包的自有代码区域不包含 `src/`、`.ts`、`.tsx`、source map 或 `sourceMappingURL`。第三方运行时依赖保持原样，不参与混淆，因此依赖自身可能包含类型声明或源码文件。混淆只提高逆向成本，并不构成加密或秘密保护边界。
+
+每个正式 tag 同时生成与运行时依赖树对应的 CycloneDX SBOM，以及记录源码 commit、构建工具精确版本、混淆状态和产物摘要的 manifest。本项目使用 MIT 许可证，完整条款见 `LICENSE`。
+
+## 源码开发
+
+```bash
+npm install
+cp config.example.yaml ~/.config/yxdash/config.yaml   # 按需修改
+export YUNXIAO_ACCESS_TOKEN=<云效个人访问令牌>          # 或在配置中用 token_cmd
+npm run dev            # 交互式 TUI（默认落在迭代视图）
+```
+
+发布前本地验证：
+
+```bash
+npm ci
+npm run release:check  # 类型、覆盖率、全依赖审计、registry 签名、混淆构建、包内容与安装后黑盒验证
+```
+
+正式发布采用 SemVer tag，tag 必须与 `package.json` 版本完全一致且指向干净提交。推荐用 `npm version patch|minor|major` 同步修改包清单与锁文件并创建 `v<version>` tag，推送 tag 后由 GitLab 流水线生成产物；npmjs 发布是受保护 tag 上的人工批准步骤。已推送 tag 不得移动：如果发布失败后又修改了产物，必须递增版本并创建新 tag。
+
+当前自托管 GitLab runner 不满足 npm Trusted Publishing 的云托管 runner 条件，因此 CI 使用项目级 protected + masked `NPM_TOKEN`：令牌必须是仅允许 `@adongguo/yxdash` 读写、允许发布绕过 2FA、具有最短可用期限的 npm granular access token，禁止写入仓库或日志。`release:bundle` 会拒绝脏工作区、非稳定 SemVer、tag/版本不一致、原始业务源码或 source map 入包，以及无法证明混淆状态的产物。
+
+启动落地行为由配置决定：`defaultView`（默认 `sprint`）决定打开哪个视图；迭代视图的 `views.sprint.groupBy`（默认 `statusStage` 按阶段分组，运行时 `g` 键可循环切换）与 `defaultAssignee`（默认 `self` 只看自己，可设 `all` 或具体用户 id）决定初始分组与过滤。命令行显式指定视图（`yxdash bugs`）优先于配置；**管道模式不受 `defaultView` 影响**，未指定视图时始终是 `bugs`，保证 agent 拿到的输出结构稳定。
+
+令牌解析顺序：`YUNXIAO_ACCESS_TOKEN` 环境变量 → 配置中的 `token_cmd`（例如从 `~/.claude.json` 的 MCP 配置读取）。令牌永不明文落盘。
+
+配置查找顺序：`$YXDASH_CONFIG` → `./.yxdash.yaml` → `~/.config/yxdash/config.yaml`。
+
+安全边界：工作目录的 `./.yxdash.yaml` 可能随任意 clone 的仓库而来，因此**其中的 `token_cmd` 会被拒绝执行**（`token_cmd` 只在用户级配置生效），加载工作目录配置时会在 stderr 提示确认。确实需要仓库级配置带 `token_cmd` 时，用 `--config ./.yxdash.yaml` 或 `$YXDASH_CONFIG` 显式指定（显式指定 = 显式信任）。
+
+## 视觉与 UI 配置
+
+默认视觉系统为 Dracula Pro：背景基准 `#22212C`、交互焦点紫 `#9580FF`、多选标记粉 `#FF80BF`、信息青 `#80FFEA`、警告黄 `#FFFF80`、错误红 `#FF9580`。紫色只编码“当前可操作焦点”，粉色只编码“已持有的多选项”，严重度颜色不复用，避免同一种颜色同时表达两个状态。光标仍使用终端反显通道，因此在彩色能力受限时也能辨认。
+
+`ui` 段可按终端和工作习惯精调：
+
+| 配置 | 默认 | 作用 |
+|---|---|---|
+| `theme` | `dracula-pro` | `dracula-pro` 使用紫色视觉系统；`terminal` 沿用终端调色板 |
+| `accentColor` / `markColor` | 主题值 | 用 `#RRGGBB` 覆盖焦点色 / 多选色 |
+| `borderStyle` | `round` | 弹层边框：`round` / `single` / `double` / `classic` |
+| `animations` | `true` | `false` 后用静态点替代 spinner 动画 |
+| `previewPosition` | `auto` | 初始预览位置：`auto` / `right` / `bottom` |
+| `footer` | `auto` | `minimal` 只保留视图切换与帮助/退出 |
+| `density` / `detailBar` | `auto` | 列表密度与完整标题提示行 |
+| `breakpoints` | `52/80/120` | `sm` / `md` / `lg` 响应式断点 |
+| `mouse` | `true` | 鼠标滚动、点击与双击 |
+
+一次性覆盖可用 `YXDASH_THEME=terminal` 或 `YXDASH_MARK_COLOR=<受支持的 ANSI 颜色名|#RRGGBB>`；环境变量优先于配置，适合排查不支持 truecolor 的远程终端。
+
+## 键位
+
+| 键 | 作用 | 键 | 作用 |
+|---|---|---|---|
+| `1-9` | 直达 section | `s` / `S` | 循环切换视图 |
+| `j/k` `↓/↑` `Ctrl+n/p` | 行移动（三套等价，弹层内通用） | `h/l` `←/→` | 相邻 section |
+| `g` / `G` | 首行 / 末行 | `Enter` / `p` | 预览开关 |
+| `P` | 预览位置（自动→右→底） | `Ctrl+d/u` | 预览翻页 |
+| `o` | 浏览器打开 | `y` / `Y` | 复制编号 / URL（有标记时复制全部标记项，一行一项） |
+| `v` | 标记/取消标记当前行并下移（多选，行首 2 格色轨 + 整行 accent；Esc 清除全部标记） | `Ctrl+k` | 命令面板：模糊搜索（中文/拼音/英文）并执行任意操作 |
+| `/` | 本地模糊筛（Esc 清除） | `r` / `R` | 刷新当前 / 全部 |
+| `e` | 编辑（状态/负责人/优先级/描述/评论） | `m` | 状态流转直达 |
+| `C` | 查看评论 | `?` / `q` | 帮助 / 退出 |
+
+鼠标（默认开启）：
+
+| 操作 | 作用 |
+|---|---|
+| 滚轮 | 指针所在区域滚动：列表移光标（卡片行 1 条/格，普通行 3 行/格）、预览/评论面板滚 3 行/格、弹层列表移 1 项/格 |
+| 单击 | 表格行/迭代条目=选中；迭代组头=折叠展开；顶部 tab=切 section；底部视图名=切视图；左栏=切迭代；弹层条目=移动选中 |
+| 双击 | 条目=开关预览（等价 `Enter`）；弹层条目=确认（等价 `Enter`）；组头双击不抖动 |
+| Shift+点击/拖选 | 交回终端：原生拖选复制、编号 OSC 8 超链接 |
+
+滚轮**只滚动内容，不切换数据源**——切 section 和切迭代都要发请求，一次滚轮动作会连发好几格，与限流预算冲突。右键/中键不接管，留给终端。关闭鼠标：配置 `ui.mouse: false`，或临时 `YXDASH_NO_MOUSE=1`；关闭后行为与未引入该特性时逐字节一致。
+
+编辑说明：
+
+- **字段编辑**：`e` 打开菜单（当前值一览）→ 选字段 → 选择式弹层（光标预置在当前值、`●` 标记、Enter 提交、Esc 返回；选中当前值 Enter 视为「未变更」不发请求）。候选严格取自**该工作项自身类型**的工作流/字段配置，负责人候选来自当前视图人员（自己标 ★）。
+- **富文本编辑**：`e→d`（描述）/ `e→c`（新增评论）挂起 TUI，把终端交给外部编辑器（解析链 `$YXDASH_EDITOR → $VISUAL → $EDITOR → nvim → vim → vi`），编辑临时 markdown 文件；**保存退出即提交**，清空正文或未修改即取消——与 Claude Code 的 vim 编辑对话框同款方案。描述基线每次现拉服务端最新（避免覆盖他人改动）；RICHTEXT 原文会作为注释块附在缓冲区末尾备份（提交时自动剥离）；提交失败保留草稿，下次同一工作项编辑时自动恢复。
+- 写操作仅在 TUI 中由显式操作触发；`--json/--plain` 管道面保持只读。
+
+迭代视图专属（master-detail：左栏迭代列表，右侧按分组折叠展示；默认只看需求——产品类/技术类/AR 三类全含，缺陷隐藏）：
+
+| 键 | 作用 | 键 | 作用 |
+|---|---|---|---|
+| `h/l` `1-9` | 切换迭代 | `g` | 分组维度：阶段→负责人→类型 |
+| `a` | 按负责人过滤（★=自己，含计数） | `b` | 显示/隐藏迭代内缺陷 |
+| `空格` | 折叠/展开光标所在分组 | `Enter` | 组头=折叠该组；条目=预览 |
+| `za` `zo` `zc` | 切换 / 展开 / 折叠当前分组 | `zs` | **只展开当前分组**（其余全折叠） |
+| `zR` `zM` | 全部展开 / 全部折叠（`c` 在两者间切换） | `zj` `zk` | 跳到下 / 上一个分组头 |
+
+折叠说明（vim 式 fold）：
+
+- **按单个阶段展开**：`zM` 全折叠 → `zj` 逐个跳分组（或 `j/k`）→ `空格`/`zo` 展开要看的那个；已经站在某条目上时，`zs` 一键变成「只展开这一个分组」。
+- 条目行上按 `空格`/`zc` 折的是**它所属的分组**，光标随即回到组头——不必先移到组头再折。
+- 折叠不丢阅读位置：任何折叠动作后光标都会锚回原来那条（条目被折起时退到它的组头）。
+- 按下 `z` 后提示行变成折叠键速查（`z… a切换 o展开 …`），此时任意非折叠键（含 `Esc`）都只是取消，不会触发原本的功能——`zq` 不会退出。
+- 「全折叠」是基线而非一次性动作：切换迭代后仍然保持折叠状态，刷新后新出现的分组也跟随基线；切换分组维度只清掉单组的例外。
+
+## Agent / 管道模式（Claude Code 等）
+
+TUI 之外，`yxdash` 同时是结构化数据源——stdout 只输出数据，警告与错误走 stderr：
+
+```bash
+yxdash bugs --json                  # 缺陷视图全部 sections，JSON（每条含 url）
+yxdash bugs --json --section 1      # 只要「我的未解」
+yxdash reqs --plain | column -t -s$'\t'   # TSV，grep/awk 友好
+yxdash sprint --json                # 当前迭代需求按阶段分组 + 每人计数
+yxdash sprint --json --assignee 卓越 --group-by assignee
+yxdash sprint --plain --with-bugs   # 连同缺陷（TSV 带 group 列）
+```
+
+- 退出码：`0` 成功 · `1` 有 section 失败 · `2` 参数/配置错误。
+- stdout 非 TTY 时自动进入 `--plain` 模式（管道安全，绝不渲染交互界面）。
+- 开发期等价形式：`npm run dev -- bugs --json` 或 `tsx src/cli.tsx bugs --json`。
+
+## 常用命令
+
+```bash
+npm run dev              # tsx 直跑 TUI
+npm run typecheck        # 严格类型检查（含测试）
+npm test                 # vitest 全量单测
+npm run test:coverage    # 覆盖率（阈值 90%）
+npm run build            # tsc 产出 dist/
+npm run smoke            # 真实 API 冒烟（需令牌，不进 CI）
+```
+
+## 设计要点（详见 docs/）
+
+- 需求/缺陷视图 = gh-dash 骨架（自绘表格 + sections tab + 预览面板）；不做多列 kanban 主视图。
+- 数据层直连 Yunxiao OpenAPI（`x-yunxiao-token`；专有云 Region 版与中心版路径分叉自动判定，可用 `edition` 显式覆盖）。
+- 防漂移：配置写状态名，启动时经 workflow 接口解析成 ID；全部解析失败时回退「全量拉取 + 本地过滤」。`sprint: current` 运行时解析（排除 backlog 伪迭代）。
+- 限流保护：令牌桶（容量 5、2/s）+ 429/5xx 指数退避 + 只刷可见 section + 元数据 TTL 缓存。
+- 刷新三重机制：自动轮询（默认 5 分钟，`intervalSeconds: 0` 关闭）+ `r/R` 手动 + 终端焦点回归触发；刷新失败保留旧数据（stale-while-revalidate）。
+- 链接：`o` 键 `execFile` 打开为主路径；OSC 8 超链接为增强（tmux 需 `set -ga terminal-features "*:hyperlinks"`）；复制经系统剪贴板，SSH 场景回退 OSC 52。
+- 逃生舱：`YXDASH_NO_ALTSCREEN=1` 禁全屏；`YXDASH_FULL_REPAINT=1` 关增量渲染（tmux/ConPTY 残影时用）；`YXDASH_NO_MOUSE=1` 关鼠标上报；`YXDASH_THEME=terminal` 临时沿用终端配色；`YXDASH_MARK_COLOR=blueBright`（或其他受支持的 ANSI 颜色名/`#rrggbb`）改多选标记色，非法值回落当前主题默认值。
+- 鼠标：SGR 编码（`?1000h`+`?1006h`，不开移动上报）；渲染与命中测试共用 `ui/layout/lists.ts` 的同一份视口算术，所见即可点；解析失败的序列原样落回键盘路径，终端不支持时零影响。tmux 需 `set -g mouse on` 才会转发。
+
+## 读写边界
+
+读为主：看板/管道查询全部只读。写操作（M3：字段修改、描述编辑、新增评论）仅在 TUI 中由显式选择/保存触发，agent 管道面（`--json/--plain`）不提供任何写入。令牌只经环境变量或 `token_cmd` 获取，永不落盘。

package/config.example.yaml

@@ -0,0 +1,56 @@
+# yxdash 配置示例。复制为 ~/.config/yxdash/config.yaml 后按需修改。
+# 令牌永不明文落盘：优先 token_cmd（从既有 MCP 配置/keychain 取），或环境变量 YUNXIAO_ACCESS_TOKEN。
+
+defaultView: sprint                          # 启动落地视图：bugs | reqs | sprint（管道模式不受影响，始终 bugs）
+organizationId: cdc72bf8-26dd-4dee-9b43-148c02dbe202
+project: adc139311c47c887b901342519          # 云效产品研发(FLOW)
+baseUrl: https://yunxiaopro-cn-beijing.devops.aliyuncs.com
+# edition: region                            # 缺省按域名自动判定；openapi-rdc.* => central，否则 region
+token_cmd: "jq -r '.mcpServers.yunxiao.env.YUNXIAO_ACCESS_TOKEN' ~/.claude.json"
+
+refresh:
+  intervalSeconds: 300                       # 自动刷新间隔；0 = 关闭
+  onFocus: true                              # 终端重获焦点时刷新当前 section
+
+views:
+  bugs:
+    sections:
+      - title: 我的未解
+        filters: { category: Bug, assignedTo: self, statusNames: [待确认, 再次打开, 处理中] }
+      - title: 我提的
+        filters: { category: Bug, creator: self, statusNames: [待确认, 再次打开, 处理中, 已修复] }
+      - title: 本迭代全部
+        filters: { category: Bug, sprint: current }
+      - title: 全部未解
+        filters: { category: Bug, statusNames: [待确认, 再次打开, 处理中] }
+  reqs:
+    sections:
+      - title: 我的进行中
+        filters: { category: "Req,Task", assignedTo: self, sprint: current, statusNames: [处理中, 开发自测中] }
+      - title: 本迭代全部
+        filters: { category: "Req,Task", sprint: current }
+  sprint:
+    groupBy: statusStage                     # statusStage(阶段) | assignee(负责人) | type(类型)；g 键运行时循环
+    defaultAssignee: self                    # self(当前登录人) | all(全员) | <用户id>
+    categories: "Req"                        # 默认只看需求(产品类/技术类/AR 都属 Req)；b 键临时叠加缺陷
+    showBugs: false                          # 迭代视图默认不展示缺陷
+    # stageNames:                            # 阶段名覆盖(默认映射实测自当前租户)
+    #   "1": 确认阶段
+
+columns:
+  bugs: [serialNumber, status, seriousLevel, priority, assignedTo, subject]
+  reqs: [serialNumber, workitemType, status, priority, assignedTo, subject]
+
+ui:
+  theme: dracula-pro     # dracula-pro(默认紫色视觉系统) | terminal(沿用终端配色)
+  # accentColor: "#9580FF" # 可选：覆盖交互焦点色，必须是 #RRGGBB
+  # markColor: "#FF80BF"   # 可选：覆盖多选标记色；YXDASH_MARK_COLOR 优先
+  borderStyle: round     # round | single | double | classic
+  animations: true      # false 时 spinner 固定为静态点，适合低动态偏好
+  previewPosition: auto # auto | right | bottom；P 键仍可在运行时循环
+  footer: auto           # auto(按宽度逐级降级) | minimal(只保留视图与帮助/退出)
+  mouse: true            # 鼠标交互(滚轮/单击/双击)；false 或 YXDASH_NO_MOUSE=1 关闭
+                         # 关闭后行为与未引入该特性时一致；开启时按住 Shift 可恢复终端原生拖选
+  density: auto          # auto(按宽度) | compact(单行) | comfortable(卡片)
+  detailBar: auto        # auto | always | off
+  breakpoints: { sm: 52, md: 80, lg: 120 }