cloudhouse-admin-cli 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 0.3.3
+
+新增官方 npm 安装渠道、手动与 Agent 安装指南；运行时接口与权限保持兼容。
+
+# 版本记录
+
+## 0.3.2
+
+- CLI 独立开源，MIT 许可、贡献和安全策略、独立测试/文档/打包流程。
+- 会话随机独占临时文件；Agent 安装拒绝父目录与悬空目标符号链接。
+- 考核附件采用0600临时文件与原子发布，避免未确认覆盖和不完整文件。
+- GitHub Releases 与网站分发同一批产物；不发布公共 npm。
+
+## 0.3.1
+
+分析过滤字段使用自有属性检查，保留0.3.0的数据分析契约。
+
+## 0.3.0
+
+独立的数据分析授权与全量业务只读查询、JSONL 导出及附件下载。
+
+## 0.2.0
+
+扩展管理命令、能力目录及五类 Agent 接入；严格参数与跨环境保护。
+
+历史包继续由网站保存，本仓库从0.3.2建立独立源码历史。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloudHouse CLI contributors
+
+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,63 @@
+# CloudHouse Admin CLI
+
+面向管理员与 Agent 的 CloudHouse 招新管理 CLI。纯 ESM，零运行时依赖，Node.js ≥18；命令入口为 `ch`，输出 JSON 信封与稳定退出码。
+
+[网站与文档](https://dayunwu.cn/cli/) · [GitHub 下载](https://github.com/LUOLIN926/cloudhouse-admin-cli/releases) · [命令参考](docs/01-command-reference.md) · [安全说明](SECURITY.md)
+
+## 安装
+
+推荐：`npm install -g cloudhouse-admin-cli@latest`。手动安装和 Agent 提示词见 [安装指南](docs/08-installation.md)。
+
+备用渠道：
+
+从 [v0.3.3 Release](https://github.com/LUOLIN926/cloudhouse-admin-cli/releases/tag/v0.3.3) 下载 `.tgz`，核对 SHA256SUMS 后安装：
+
+```sh
+npm install -g ./cloudhouse-admin-cli-0.3.3.tgz
+ch --version
+ch help
+ch capabilities
+```
+
+便携 ZIP 解压后通过 `node cloudhouse-admin-cli/bin/ch.mjs --version` 运行。官方 npm 包：cloudhouse-admin-cli；推荐通过 npm 安装。Windows 可用 PowerShell `Get-FileHash` 核对 SHA-256；macOS 可用 `shasum -a 256`，Linux 可用 `sha256sum`。
+
+## 登录与使用
+
+```sh
+ch login --profile prod
+ch auth status --profile prod --json
+ch candidates list --profile prod --json
+ch analysis resources --profile prod --json
+ch analysis export users --out ./candidates.jsonl --profile prod
+```
+
+最后一条示例的资源名请以 `ch analysis resources` 返回的实际目录为准。登录使用终端隐藏输入；自动化可从受保护环境注入 CH_PASSWORD/CH_TOKEN，避免命令行、shell 历史、CI 日志或聊天中出现凭据。请勿提交会话、分析导出、附件或真实业务数据。
+
+默认 profile 为 local；生产须明确指定 prod。部署到其他服务时使用 `--base-url https://your-service.example/api`。公开源码并不授予 CloudHouse 服务访问权；所有服务权限由后端验证。数据分析权限是独立的全量只读权限，不增加业务写权限。资料出题命令要求配套后端，不能仅凭 CLI 版本判断可用。
+
+## Agent 接入
+
+支持 Codex、DeepSeek Harness、OpenCode、OpenClaw 与 pi。所有接入使用同一技能与 CLI，不包含 MCP 服务或账号凭据。
+
+```sh
+ch agent install codex --scope user
+# 可替换为 dsh / opencode / openclaw / pi；项目范围用 --scope project
+```
+
+宿主需启用的步骤由命令返回。详见 [接入指南](docs/03-agent-setup.md) 与 [Agent 契约](docs/02-agent-contract.md)。
+
+## 开发与构建
+
+```sh
+npm test
+npm run check:security
+npm run docs
+npm run sync:integrations
+npm run build:release
+```
+
+测试仅连接本地模拟后端，不需要生产账号。构建输出到 dist/，包含两个 CLI 包、五个接入包、SHA256SUMS、release.json。需要系统 zip 和 npm；Windows 建议 WSL 构建。后端/管理页面不属于本仓库；脱敏接口快照测试不等于在线后端验证。
+
+## 许可
+
+代码采用 [MIT](LICENSE)。CloudHouse 品牌及服务访问权不随软件许可证授予；第三方与品牌说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/SECURITY.md

@@ -0,0 +1,11 @@
+# 安全策略
+
+维护最新 GitHub Release 的安全修复。请通过本仓库 Security → Report a vulnerability 私密报告；若入口暂不可用，先创建不含漏洞细节、凭据或业务数据的 issue，请维护者开启私密报告。不要在公开 issue、PR、日志或截图中提交可利用细节或敏感数据。
+
+CLI 不绕过服务授权。数据分析可读取联系方式、答卷等敏感业务数据，使用者须具备授权并保护输出文件。不要向不受信任的 Agent、模型服务或插件提供这些数据。只在自己授权的后端运行；生产使用 HTTPS，HTTP 仅用于受信任的本地开发。
+
+会话目录权限0700、会话文件0600；明文 token 由本机操作系统账户保护，不是加密保险箱。--show-token 是显式输出凭据的选项，避免在录屏、共享终端和 CI 中使用。CH_TOKEN 属于调用者明确提供的凭据来源，须与目标环境匹配；磁盘会话跨环境默认拒绝，--allow-profile-mismatch 会明确放行。
+
+请求不跟随重定向；续期更新进程内及磁盘 token。写入超时不能视为未执行；先查询结果，只有能力目录明确支持的动作才能使用 requestId 幂等重放。ch api 提供灵活请求能力，不扩大后端权限。
+
+下载与导出默认不覆盖，--force 是显式替换；导出仅在全部分页成功后发布完整文件。多页读取不是同一时刻的数据库快照。安装拒绝安装路径内符号链接；同一操作系统用户持续修改目标目录的竞争攻击不在本工具隔离能力之内。建议在受保护的本机目录安装与保存导出。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# 第三方与品牌
+
+CLI 使用 Node.js 内置模块，没有第三方运行时依赖。Node.js、npm、系统 zip 及 CI 工具遵循各自许可证，不作为本仓库重新授权的代码。
+
+Agent 适配中的 Codex、DeepSeek Harness/Cordis、OpenCode、OpenClaw、pi 名称及规范属于对应项目。适配源码由本项目提供，宿主不随包分发；DSH 声明 Cordis peer dependency。MIT 许可不授予这些品牌权利，不暗示官方背书。
+
+CLI 网站视觉资产与 CloudHouse Logo 不随此独立仓库分发；仓库只包含 CLI、文档、测试与 Agent 适配。

package/bin/ch.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs'
+
+run(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code
+  })
+  .catch((err) => {
+    process.stderr.write(`内部错误：${err && err.stack ? err.stack : String(err)}\n`)
+    process.exitCode = 1
+  })

package/docs/00-overview.md

@@ -0,0 +1,71 @@
+# 管理后台 CLI（ch）总览
+
+版本 **0.3.3**，Node.js ≥18，纯 ESM、零运行时依赖。共 98 条命令注册项（AI 多动作命令另列动作），面向管理员与 agent。
+
+## 安装与快速开始
+
+从 https://dayunwu.cn/cli/ 下载 .tgz 或便携 ZIP。
+
+```bash
+npm install -g ./cloudhouse-admin-cli-0.3.3.tgz
+ch --version
+ch capabilities --json
+# 输入已有管理员凭据；不要将密码粘贴到 shell 历史
+ch login --profile prod
+ch whoami --profile prod --json
+ch candidates list --profile prod --keyword 张三 --json
+ch agent install codex --scope user
+```
+
+仓库开发：`npm --prefix cli link`，或 `node cli/bin/ch.mjs`。便携 ZIP 无需全局安装，解压后运行 `node cloudhouse-admin-cli/bin/ch.mjs --help`。所有平台使用同一 Node 包，本轮未提供原生二进制。
+
+## 覆盖与边界
+
+- 分别核算语义命令覆盖、`ch api` 通用可达和 mock 行为测试覆盖；见 [审查报告](04-audit.md) 与 [覆盖表](06-coverage.md)。端点登记不等于参数完整、测试通过或生产已发布。
+- 管理员、组别、候选人、报名、方案、场次、面试、评价、通知、现场助手、上传下载、签到、飞书和 AI Coding 均有语义命令；六个原兜底接口已接入。
+- 新增资料上传、预览、出题、任务查询、确认共五个端点，需要 material-authoring 新版后端。本轮不发布这些后端改动，旧后端可返回 exit 8/9。
+- `capabilities` 的权限描述是调用指引，最终权限与功能开关始终由后端判定。
+
+## 配置与凭据
+
+| 来源 | 作用 |
+|---|---|
+| --profile local/prod | 默认 local：http://127.0.0.1:8080/api；prod：https://api.dayunwu.cn/api |
+| --base-url / CH_BASE_URL / CH_API_BASE | 显式 API 根地址 |
+| CH_PROFILE | 默认环境选择 |
+| CH_TOKEN | 显式提供调用环境的 token，优先于磁盘会话 |
+| CH_STUDENT_NO / CH_PASSWORD | 登录环境变量；避免把密码写进 shell 历史 |
+| CH_CONFIG_DIR | 配置与会话目录，默认 ~/.config/cloudhouse-cli |
+| CH_AGENT_HOME | agent 安装的用户根目录覆盖，用于隔离测试 |
+| CH_CHECKIN_SCREEN_TOKEN | 签到大屏 token，只经 header 发送 |
+
+优先级：flag > 环境 > config.json > 内置。未知 profile 不自动回落。
+
+## 会话、安全与重试
+
+- session.json 权限 0600，配置目录 0700；续期同时更新本进程和匹配的磁盘会话。环境 token 不被写入新会话。
+- 磁盘会话的 baseUrl 不匹配时默认 exit 2，阻止凭据发送；跨环境需显式 `--allow-profile-mismatch`。CLI 不自动重新登录。
+- stdout 默认管道输出单行 JSON 信封，TTY 默认人类输出；agent 使用 `--json`。10 档语义化 exit code 见契约。
+- requestId 只适用于 `ch ai *` 的写命令中 capabilities 标注支持的操作；资料上传例外，其他业务写接口不支持去重。
+- 未指定版本的乐观锁冲突最多自动重读重试两次，并更换 requestId；显式版本不自动重试。
+- 敏感写操作缺 reason 则本地拒绝；共 9 处，reason ≤200字。外部通知命令需用户明确授权，不用于连通性测试。
+- 未知/不适用参数、多余位置参数 exit 2；`ch api` 保留宽松参数解析。非 JSON、无效 JSON 信封、重定向均不会误报成功。
+
+## 文档与验证
+
+[命令参考](01-command-reference.md) · [Agent 契约](02-agent-contract.md) · [五类接入](03-agent-setup.md) · [审查报告](04-audit.md) · [发布说明](05-release.md)
+
+运行 `npm --prefix cli test`。契约测试双向核对前端 API、后端管理端点和注册表，新增端点必须作显式接入决定；行为测试通过本机 mock 后端核对请求，不使用生产数据。
+
+## 全量只读数据分析（0.3.0）
+
+现有管理员在 v36 迁移时统一开启；新建账号默认关闭，仅 SYSTEM 可修改。Web 仅增加授权开关，现有数据范围及写权限保持原样。
+
+```bash
+ch auth status --profile prod --json
+ch analysis resources --profile prod --json
+ch analysis list profiles --profile prod --json
+ch analysis export profiles --profile prod --out ./profiles.jsonl
+```
+
+分析命令使用独立 API，全量跨组读取受字段白名单控制；权限关闭不会取消其他管理权限。详见 [数据分析指南](07-data-analysis.md)。