一个由真实 OpenAI-compatible LLM 驱动的非诊断性抑郁筛查辅助 Agent：它在确定性安全规则和专业问题框架约束下开展开放式访谈，动态追问并生成可核对的结构化结果。
Demo 使用边界： 当前专业问题框架、安全规则和帮助资源仍是合成内容，仅用于功能演示。本项目不是医疗产品，不提供诊断、治疗、用药建议或最终风险等级，也不能用于真实患者、临床决策或紧急求助。
- 持续运行的中文交互式终端界面，在同一界面完成同意、访谈、摘要核对和退出。
- 知情同意，以及跳过、暂停、恢复、退出和撤回同意。
- 每轮用户输入先执行确定性安全规则；命中时停止普通模型生成，展示固定安全内容并进入人工复核。
- 真实 LLM 根据当前回答、已有事实、已问问题、跳过项、不确定点、矛盾和专业问题框架动态生成下一条问题。
- 每轮 LLM 输出经过严格 Schema 校验，并保存有来源引用的事实、不确定点和矛盾。
- LLM 判断是否还需追问，但状态转换、同意、安全和最终写入仍由确定性代码控制。
- LLM 生成结构化摘要，用户可确认、修正或拒绝，再进入模拟专业复核。
- 会话状态查看、详细访谈状态检查、记录导出、事件回放和本地数据检查。
Fake Inference 只用于单元测试、无网络测试和自动化回归，不是完整业务 Demo。模型故障降级也必须显式启用，并会在输出和会话状态中标明。
推荐使用 Windows PowerShell 和 Node.js 22.x LTS。以下命令均在项目根目录执行。
- Windows 10/11 与 PowerShell 5.1 或更高版本；
- Node.js 22.x LTS；当前 Demo 不支持 Node.js 23/24；
- Git；
- 可访问 npm registry、GitHub 和所配置模型服务的网络；
- 一个支持 OpenAI Chat Completions 格式和 JSON Object 输出的模型；
- 对应模型服务的 API Key。
检查环境：
node --version
npm --version
git --versionnode --version 应显示 v22。
npm run hypha:bootstrap
npm run buildhypha:bootstrap 会根据 hypha.lock.json 检出并校验指定 Hypha 提交，构建 Hypha 包并安装本项目依赖。不要自行切换或修改 Hypha/。
CLI 不会自动读取 .env；.env.example 只是变量模板。推荐在启动 CLI 的同一个 PowerShell 窗口中设置：
$env:SCREENING_RUNTIME_MODE = "development"
$env:SCREENING_MODEL_MODE = "openai-compatible"
$env:SCREENING_MODEL_ALIAS = "replace-with-model-name"
$env:SCREENING_OPENAI_BASE_URL = "https://api.openai.com/v1"
$env:SCREENING_OPENAI_API_KEY = "replace-with-your-api-key"
$env:SCREENING_ALLOW_MODEL_FALLBACK = "0"
$env:SCREENING_DATA_DIR = ".\data"SCREENING_MODEL_ALIAS 必须填写模型服务实际接受的模型名。Base URL 可替换为其他 OpenAI-compatible 服务地址。
不要把真实密钥写入 README、提交到 Git 或与日志一起分享。也可以使用仅包含密钥的本地文件：
Remove-Item Env:SCREENING_OPENAI_API_KEY -ErrorAction SilentlyContinue
$env:SCREENING_OPENAI_API_KEY_FILE = "C:\secure\screening-api-key.txt"SCREENING_OPENAI_API_KEY 和 SCREENING_OPENAI_API_KEY_FILE 只能设置一个。关闭当前 PowerShell 后，这些临时环境变量会失效。
缺少模型名或凭据时，start 会返回 MODEL_ALIAS_REQUIRED 或 MODEL_CREDENTIAL_REQUIRED，不会静默切换到 Fake Inference。
默认 SCREENING_ALLOW_MODEL_FALLBACK=0。模型不可用或输出不符合契约时，当前命令会明确失败，体验者可以重试。
只有确实需要展示故障处置时才设置：
$env:SCREENING_ALLOW_MODEL_FALLBACK = "1"此时系统只使用专业框架中的固定内容继续有限流程，输出会写明“受限降级模式”，status --details 中 modelDegraded 为 true。该模式不能被视为完整 Agent Demo。
npm start -- doctor
npm start -- config validate用于完整 Demo 时，doctor 应显示：
{
"modelMode": "openai-compatible",
"modelConfigured": true,
"demoReady": true
}config validate 中 productionReady: false 是当前 Demo 的预期结果，因为仓库内专业内容是未签名的合成配置。
配置并构建完成后，推荐直接运行：
npm run chat仓库中的 .npmrc 会抑制 npm 的脚本前缀；界面启动时不会先显示包名和 node dist/...。npm start 和 npm start -- chat 仍然可用，但不再是推荐方式。
交互界面由 @earendil-works/pi-tui 驱动，使用终端备用屏幕和差分渲染。它只更新变化的行；退出后恢复原屏幕，不会在 scrollback 中留下多套重复页面。界面固定包含：
- 紧凑启动页：产品标题、模型连接状态、非诊断说明，以及“开始筛查、恢复会话、帮助、退出”入口；
- Agent 名称、当前模型、连接状态、业务阶段和简短会话 ID；
- 一份持续对话历史；
- 原地更新的状态栏和 Loader；
- 支持光标移动、退格、历史输入、中文和括号粘贴的固定编辑器；
- 输入
/时出现的命令补全列表。
窗口大小变化时会按新的列宽重新计算中文显示宽度并排版。正常界面不会显示原始 JSON、完整异常、绝对路径、Schema 细节或 SQLite ExperimentalWarning。
当前模型调用要求先完成结构化 JSON 校验和禁止内容检查，业务服务尚不暴露可安全展示的自然语言 token 流。因此界面会原地显示当前助手占位消息，并在校验通过后替换为完整回复；不会把未校验的 JSON 分片提前展示给用户。
支持的基本命令：
/help 查看帮助
/summary 在当前界面生成并核对摘要
/pause 暂停会话；之后直接输入即可恢复
/withdraw 撤回同意并停止处理
/status 查看简洁的会话进度
/exit 保存当前会话并退出终端界面
模型失败时还可以使用 /retry 重试刚才的输入。失败输入不会保留在业务事实中，重试不会产生重复事实。
控制命令不会作为用户回答保存，也不会发送给访谈模型。空内容不会发送。
当助手给出编号选项时，可以直接输入 1、2 等数字。待选项会保存在会话中，程序会优先将数字解析为上一轮对应选项，并把该语义和最近双向对话一并交给模型，不会把孤立数字误当成情绪评分。启动页选择 2 并粘贴完整 session_… ID，可恢复已保存会话。
需要查看开发调试信息时使用：
npm run start:debug调试模式可能显示技术错误和运行时警告，不适合普通 Demo 展示。
- 运行
npm run chat，在启动页输入1选择“开始筛查”。 - 阅读知情同意说明，输入
yes。 - 回答助手的开放式问题。例如：
最近总是很早醒，白天上课没有精神。
输入后会立即显示在对话历史中。模型处理期间顶部状态变为“正在分析”。
- 继续回答 LLM 根据当前上下文生成的问题。问题不会按固定数组顺序播放。
- 随时输入
/status查看访谈轮次、事实数、不确定点、矛盾点和模型降级状态。 - 信息足够时输入
/summary。摘要会直接显示在当前终端中，不需要复制 session ID。 - 在摘要菜单中选择：
[1] 确认
[2] 修改
[3] 拒绝
[4] 返回对话
选择修改后，应输入一份完整的修正版摘要。该内容会先经过安全检查，然后确定性替换旧摘要、旧工作事实、不确定点和矛盾，再次等待确认。
- 确认摘要后，系统会在同一界面提示已提交专业复核。
- 输入
/exit离开。
/pause：暂停但保留进度；终端保持运行，直接输入新的回答即可恢复。/exit：如果正在访谈，会先暂停会话再退出界面；不会撤回同意。Ctrl+C：中断当前生成并立即恢复终端；已完成持久化的会话数据会保留。/withdraw：撤回同意，停止后续处理并删除普通对话及摘要。
分别运行两次 npm run chat，第一轮使用不同的合成回答：
会话 A：最近总是很早醒，白天没有精神。
会话 B：最近不太想和同学说话，但睡眠和平时差不多。
在界面中比较紧接着出现的问题。真实模型验收应满足：
- 后续问题措辞或追问方向不同；
- 两次会话都显示模型连接成功；
/status显示模型未降级；- 后续摘要中的事实和不确定点与各自回答对应。
如需开发排查，可使用下面保留的非交互命令检查详细状态。
原有命令继续可用：
npm start -- doctor
npm start -- config validate
npm start -- status <session-id>
npm start -- status <session-id> --details
npm start -- resume <session-id>
npm start -- summary <session-id>
npm start -- replay <session-id>
npm start -- export <session-id> --user-ref demo-user
npm start -- review list --professional-ref reviewer-1这些命令用于测试、恢复和排查。普通 Demo 体验者不需要在每个阶段重新执行带 session ID 的命令。
Docker 不是推荐路径。构建前仍需准备锁定版本的 Hypha：
npm run hypha:bootstrap
docker build -t depression-screening-cli:demo .
docker run --rm --env-file .env depression-screening-cli:demo doctor交互运行并持久化数据：
docker volume create depression-screening-data
docker run --rm -it --env-file .env -v depression-screening-data:/app/data depression-screening-cli:demo chat.env 中不得包含要写入镜像或提交到 Git 的真实密钥。
自动化测试显式使用 Fake Inference 或本地模拟 OpenAI-compatible 服务，不需要真实 API Key：
npm run typecheck
npm run build
npm test真实模型验收会调用配置的模型服务，并验证不同回答产生不同追问、结构化证据和摘要：
$env:SCREENING_RUN_REAL_MODEL_TEST = "1"
npm run test:model:acceptance该测试会产生模型调用费用，只能使用合成输入。
完整 Demo 必须配置真实模型。按“配置真实模型”设置模型名和一个凭据来源，然后重新运行 doctor。
检查 SCREENING_MODEL_MODE 是否为 openai-compatible，并确认模型名和 API Key/Key 文件已在当前终端设置。
模型返回内容没有通过 JSON 解析、结构化契约或业务边界校验。系统会先自动再次调用模型修复一次；两次都失败时才显示该错误，并且不会用 Fake 结果冒充成功。输入会保留在当前界面，可使用 /retry 重试且不会重复写入。持续失败时应检查事件日志中的脱敏原始响应、JSON 解析结果、Zod 字段错误和业务校验错误，或更换支持 JSON Object 输出且指令遵循能力更好的模型。
保持默认配置时重试即可。只有为了演示故障处置才显式设置 SCREENING_ALLOW_MODEL_FALLBACK=1；降级结果不属于完整 Demo。
这是预期结果。内置问题框架、安全规则和帮助资源为合成内容，未经过机构签名审批。
CLI 不自动加载 .env。请在当前 PowerShell 设置 $env:变量名，或仅在 Docker 中使用 --env-file .env。
同时设置了 API Key 和 Key 文件。删除其中一个。
确保后续命令使用相同的 SCREENING_DATA_DIR。全局参数必须位于子命令之前：
npm start -- --data-dir .\demo-data status <session-id> --details确认使用 Node.js 22.x。Node.js 23/24 可能要求额外的 Python/C++ 编译工具链，不属于推荐 Demo 环境。
这是当前 Node.js SQLite 后端提示。若 doctor 和会话命令正常返回，通常不影响 Demo。
- 专业问题框架、安全规则和帮助资源仍是合成内容，未获得临床或机构审批。
- 不同 OpenAI-compatible 模型的 JSON 输出、延迟、费用和追问质量会有差异。
- 专业复核的
--professional-ref是演示标识，没有真实登录、资质校验或任务分配系统。 - 数据保存在单机本地目录，不适合多人并发、跨设备共享或生产部署。
- CLI 主要使用中文提示，尚无完整多语言界面。
- 尚未提供独立安装包；首次安装需要 Node.js 22.x、Git、网络和源码。
- 本项目不是危机干预工具，合成帮助资源不能替代所在地真实紧急服务。