Qdecision

本地优先的中文决策引擎。
Local-first Chinese decision engine.

Qdecision 不做泛 AI 聊天工具。它做的是另一件事：把一句模糊纠结压缩成可执行判断。
Qdecision is not a generic AI chat app. It compresses one messy question into an actionable judgment.

• 一句当前倾向 / A clear current tilt
• 一个今天就能做的动作 / A first move you can take today
• 三条真正有差异的未来路径 / Three genuinely differentiated future paths

Why This Repo Exists / 为什么这个仓库存在

大多数“AI 决策”产品最后都会滑向两个问题：
Most AI decision products tend to collapse into two problems:

1. 变成陪聊，输出很多话，但不真正收束判断
   They become chatty companions that generate many words without converging on a real judgment.
2. 变成长问卷，输入成本很高，用户在开始前就流失
   They become long questionnaires with high input cost and user drop-off before the real value starts.

Qdecision 的目标正好相反：
Qdecision is designed in the opposite direction:

• 先降低输入负担 / Lower the input burden first
• 只追问会改变结果的变量 / Ask only the variables that can change the answer
• 先给判断，再给解释 / Deliver judgment first, explanation second
• 默认支持本地运行 / Default to local execution instead of remote-first infrastructure

What Makes It Different / 它和普通 AI Chat 有什么不同

Dimension / 维度	Typical AI Chat / 普通 AI Chat	Qdecision
Input / 输入方式	Open-ended conversation / 一直开放对话	One raw question, then 2 to 4 key follow-ups / 先一句问题，再进入 2 到 4 个关键追问
Output goal / 输出目标	Keep talking / 尽量“聊得多”	Make the judgment clearer / 尽量“判断得清楚”
Result structure / 结果结构	Generic advice block / 一段泛化建议	Judgment, action, boundary, future paths / 判断、行动、边界、未来路径
Interaction rhythm / 交互节奏	Single open loop / 一直开放式	Quick first, full second / 先 quick，再 full
Local runability / 本地可运行性	Often secondary / 常常不是重点	Ollama + SQLite by default / 默认 Ollama + SQLite 可跑

Repository Status / 仓库状态

当前仓库已经具备完整主链路：
The repository already includes the full product loop:

• 首页输入 / Home input
• 启动过渡页 / Start transition
• 关键追问 / Clarifying questions
• quick / full 双阶段生成 / Two-stage quick and full generation
• 单列结果页 / Single-column result narrative
• 历史记录与反馈 / History and feedback
• 匿名 owner 隔离 / Anonymous owner isolation
• Vitest + Playwright 验证 / Vitest + Playwright coverage

当前仓库质量门槛：
Current quality gates:

• npm run check
• npm run build
• npm run test:e2e

Product Glimpse / 产品预览

Home / 首页	Result / 结果页

End-to-End Flow / 端到端流程

flowchart LR
    A[Home Input] --> B[Create Session]
    B --> C[Classify]
    C --> D[Generate Questions]
    D --> E[Analyze]
    E --> F[Quick Judgment]
    F --> G[Full Report]
    G --> H[Result Narrative]
    H --> I[History and Feedback]

Loading

Feature Snapshot / 功能快照

• 首页极简输入 + 示例起手 / Minimal home input plus guided starters
• 启动过渡页，先拆问题再进入追问 / Start transition that frames the problem before analysis
• 2 到 4 个关键追问，降低表达负担 / 2 to 4 key follow-ups instead of a long form
• quick + full 双阶段结果生成 / Two-stage quick and full generation
• 结果页单列裁决流 / Single-column result narrative:
  • 主判断 / Main judgment
  • Closing line
  • 为什么这样判断 / Why this judgment
  • 第一行动 / First action
  • 判断边界 / Judgment boundary
  • Future path tree
• Ollama / OpenAI provider 切换 / Ollama and OpenAI provider switching
• 匿名浏览器 owner 隔离 / Anonymous browser owner isolation
• 历史记录与反馈 / History and feedback
• Zod 校验 + JSON 修复 + fallback / Zod validation, JSON repair, and fallbacks
• Vitest + Playwright

Quick Start / 快速开始

Fastest path / 最快路径

如果你希望最少步骤跑起来，直接执行：
If you want the shortest path to a running app:

npm install
npm run start:local

这个脚本会自动完成以下动作：
This script will automatically:

• 补 .env / create .env if missing
• 准备本地 SQLite / prepare local SQLite
• prisma generate
• prisma db push
• 如果默认 provider 是 Ollama，则检查服务和模型 / check Ollama service and models when Ollama is the default provider
• 启动开发服务器 / start the development server

Manual path / 手动路径

1. Install / 安装

npm install
cp .env.example .env

2. Choose your provider / 选择 provider

Option A: Ollama

ollama list

默认模型 / Default models:

• glm-4.7-flash:latest
• qwen3.5:35b

Option B: OpenAI

在 .env 中设置：
Set the following in .env:

DEFAULT_LLM_PROVIDER=openai
OPENAI_API_KEY=your_key_here

默认 OpenAI 模型 / Default OpenAI models:

• gpt-5-mini
• gpt-5.4

3. Prepare the database / 准备数据库

touch prisma/dev.db
npm run db:push

4. Start / 启动

npm run dev

打开 http://127.0.0.1:3000
Open http://127.0.0.1:3000

Architecture / 架构

Runtime flow / 运行流程

1. 用户在 / 输入一句自然语言问题 / The user enters a raw decision question on /
2. 服务端创建 DecisionSession / The server creates a DecisionSession
3. classify 识别领域、紧迫度、隐藏张力、缺失信息 / classify extracts domain, urgency, hidden tensions, and missing information
4. generateQuestions 生成 2 到 4 个关键追问 / generateQuestions produces 2 to 4 key follow-ups
5. 用户在 /analyze 完成回答 / The user answers on /analyze
6. quick 先给当前判断 / quick generates the first tilt
7. full 再补完整报告、行动和未来路径 / full adds the full report, action, and future paths
8. /result/[sessionId] 把它们整合成单列叙事结果页 / /result/[sessionId] merges them into one narrative result page

Core folders / 核心目录

src/app/                    # 页面与 API 路由 / pages + route handlers
src/components/             # home / chat / result / history UI
src/lib/decision/           # 决策链路与 fallback / intake / pipeline / fallback / report / repository
src/lib/llm/                # provider 路由与结构化解析 / provider routing / prompts / structured parsing
src/types/                  # decision / api / feedback types
prisma/                     # Prisma schema + local SQLite db
docs/                       # 产品、调试与架构文档 / product, debugging, and architecture docs

更完整的结构说明见 docs/ARCHITECTURE.md。
See docs/ARCHITECTURE.md for a fuller architecture walkthrough.

Model Strategy / 模型策略

默认采用双阶段模型策略：
The default setup uses a two-stage model strategy:

• fast model 用于 classify / generateQuestions / quick
  Used for classify / generateQuestions / quick
• deep model 用于 fullReport / personalize
  Used for fullReport / personalize

默认 provider 组合 / Default provider presets:

• Ollama: glm-4.7-flash:latest + qwen3.5:35b
• OpenAI: gpt-5-mini + gpt-5.4

Quality Gates / 质量门槛

npm run lint
npm run typecheck
npm run test
npm run build
npm run check
npm run test:e2e

npm run check 会串行执行 lint + typecheck + test。
npm run check runs lint + typecheck + test in sequence.

API Surface / API 列表

• POST /api/decision/start
• POST /api/decision/answer
• POST /api/decision/quick
• POST /api/decision/full
• POST /api/decision/retry
• GET /api/decision/session/[sessionId]
• GET /api/decision/history
• GET /api/llm/options
• POST /api/feedback
• GET /api/health

Reliability Notes / 健壮性说明

• 所有结构化输出都先走 Zod 校验 / All structured outputs are validated by Zod first
• JSON 不合法时会自动尝试一次修复 / Invalid JSON triggers one repair attempt
• classify / questions / quick / full / personalize 都有 fallback / classify / questions / quick / full / personalize all have fallbacks
• history / session / answer / full / retone / feedback 都受 qdecision_viewer_id owner 隔离 / history / session / answer / full / retone / feedback are isolated by qdecision_viewer_id
• 每个响应头都带 x-request-id / Every response includes x-request-id

Open Source Posture / 开源治理

这个仓库目前已经包含：
This repository already includes:

• CONTRIBUTING.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• GitHub issue templates
• PR template
• CI workflow

Docs / 文档

• 功能说明 / Functional Overview
• 产品设计说明 / Product Design Notes
• 调试与日志 / Debugging and Logs
• 架构说明 / Architecture

Contributing / 参与贡献

欢迎贡献，优先方向：
Contributions are welcome, especially in:

• 主链路体验 / core user flow quality
• 可复现性 / reproducibility
• 测试覆盖 / test coverage
• 文档清晰度 / documentation clarity

开始前先看 CONTRIBUTING.md。
Read CONTRIBUTING.md before opening a PR.

License

MIT