Developer documentation开发者文档
How CalmSharp works.CalmSharp 如何运行。
A guide to the current edge architecture, account API and data boundaries. Implementation details are separated from acceptance evidence.当前边缘架构、账户 API 与数据边界的指南。实现细节与验收证据分别说明。
Presentation, inference and storage.展示、推理与存储。
Two TypeScript Workers serve the public site and Ari. HTML is rendered on the Worker; interaction uses browser DOM code. Shared packages supply design tokens, brand assets, localized copy, prompt construction and deterministic security checks.两个 TypeScript Worker 分别提供官网与 Ari。HTML 在 Worker 中生成，交互使用浏览器 DOM 代码。共享包提供设计变量、品牌资源、本地化文案、提示词构建与确定性安全检查。
The public site has no account database binding. Its evaluation endpoint reads a fixed public upstream and does not forward visitor credentials. Account operations run on friend.calmsharp.com.官网没有账户数据库绑定。官网评测接口读取固定的公开来源，不转发访客凭据。账户操作在 friend.calmsharp.com 上执行。
Service boundaries.服务边界。
- calmsharp-site
- Public routes, reading pages and same-origin font assets. lab, evals and docs subdomains render their corresponding page; www and be redirect to the main site.提供公开路由、阅读页面与同源字体。lab、evals 与 docs 子域名呈现对应页面；www 与 be 跳转到主站。
- calmsharp-friend
- Ari UI, authenticated account API, streaming inference and administrative endpoints.提供 Ari 界面、账户鉴权 API、流式推理与管理员接口。
- Cloudflare D1
- Account records, sessions, goals, consented memories, registered messages and operational counters. Anonymous conversation text is kept by the browser in the current UI.保存账户、会话、目标、已授权记忆、注册用户消息与运行计数。当前界面的匿名对话文本保存在浏览器。
- Workers AI
- Processes supplied message context. Configuration names a default model; fallback selection can change the actual model. A configured identifier is not an immutable weight revision.处理传入的消息上下文。配置指定默认模型，回退可能改变实际使用的模型。配置标识符不是不可变的权重修订号。
Authenticate on the Ari host.在 Ari 域名上鉴权。
Protected routes require Authorization: Bearer followed by a valid session token. The Worker hashes it and verifies expiry and revocation. Credentials belong in request headers, never URLs, public HTML or source control.受保护的接口需要 Authorization: Bearer 与有效会话凭据。Worker 对凭据进行哈希处理，并检查到期与撤销状态。凭据应放在请求头中，不能进入 URL、公开 HTML 或版本库。
curl https://friend.calmsharp.com/api/auth/me \
--header 'Authorization: Bearer SESSION_TOKEN'The public site is not an account API proxy. An administrator key has a separate role from a user session, and must never be sent by public-page scripts.官网不是账户 API 代理。管理员密钥与用户会话承担不同角色，公开页面脚本不能发送管理员密钥。
Current account API.当前账户 API。
- GET
/api/auth/me - Read the current identity and memory settings. HTTP 401 means the session is invalid; a network failure does not.读取当前身份与记忆设置。HTTP 401 表示会话无效，网络失败不等于身份失效。
- GET / POST
/api/conversations - List owned conversations or create one. Creation accepts title and an optional UUID request_id; the same key is deduplicated within the authenticated owner.列出当前用户的对话或创建对话。创建接受 title 与可选 UUID request_id，同一用户的相同键会去重。
- GET / DELETE
/api/conversations/:id - Read owned conversation details and ordered messages, or delete the conversation and its linked messages and feedback. Anonymous dialogue text is stored by the browser rather than returned from D1.读取自己的对话详情与按时间排列的消息，或删除对话及关联消息、反馈。匿名对话文本保存在浏览器，不由 D1 返回。
- POST
/api/chat - Send message, conversation_id and language (en or zh-CN). Success streams UTF-8 plain text, not SSE frames. Read response.body incrementally. Authentication, challenge, limits or service availability can reject a request before streaming.发送 message、conversation_id 与 language（en 或 zh-CN）。成功响应为 UTF-8 纯文本流，而非 SSE 帧；逐步读取 response.body。鉴权、人机验证、限额或服务状态可能在流开始前拒绝请求。
- GET / POST
/api/goals - Read or create account goals. PATCH /api/goals/:id edits title and description; the owner check still applies.读取或创建账户目标。PATCH /api/goals/:id 可编辑标题与描述，并执行归属检查。
- GET / POST
/api/goals/:id/steps - Read ordered milestones or create one with title. PATCH /api/goals/:id/steps/:stepId accepts is_completed; DELETE removes the owned milestone. Parent-goal ownership is checked first.读取排序后的里程碑或以 title 创建。PATCH /api/goals/:id/steps/:stepId 接受 is_completed，DELETE 删除自己的里程碑。所有操作先检查父目标归属。
- GET / POST
/api/memories - Read or save confirmed memories. Saving requires a registered account with memory enabled. PUT /api/memories/:id edits content; DELETE removes the owned record.读取或保存已确认记忆。保存需要注册账户并开启记忆。PUT /api/memories/:id 修改内容，DELETE 删除归属当前用户的记录。
- GET / PUT
/api/settings - Read or update allow_long_term_memory, ai_character_name and language (en or zh-CN). A settings update records consent; disabling memory does not delete saved records.读取或更新 allow_long_term_memory、ai_character_name 与 language（en 或 zh-CN）。更新设置会记录授权；关闭记忆不会删除已保存记录。
- POST
/api/auth/logout - Revoke the presented session. Treat logout as confirmed only after a successful response.撤销当前会话，仅在成功响应后视为退出已确认。
Streaming and error responses流式响应与错误
Check the HTTP status before reading the stream. Pre-stream failures use a JSON error body: 400 for invalid input, 401 for an invalid session, 403 for consent or challenge requirements, 404 for an inaccessible conversation, 429 for limits, and 503 for unavailable generation. The current plain-text stream has no final success event or message ID. End-of-stream alone does not verify database persistence.读取流前先检查 HTTP 状态。流开始前的失败使用 JSON 错误体：400 表示输入无效，401 表示会话无效，403 表示授权或人机验证要求，404 表示无法访问对话，429 表示限额，503 表示生成服务不可用。当前纯文本流没有最终成功事件或消息编号，仅流结束不能证明数据库保存成功。
If Turnstile is configured, send a valid challenge response in the cf-turnstile-response header or turnstile_token body field. Stop receiving with AbortController; this does not by itself prove cancellation of provider computation. Do not automatically resubmit chat after an uncertain result: chat requests do not have the conversation-creation deduplication guarantee.如已配置 Turnstile，请通过 cf-turnstile-response 请求头或 turnstile_token 请求体字段提交有效验证结果。可用 AbortController 停止接收，但这本身不能证明供应商停止计算。结果未知时不要自动重发聊天：聊天请求没有对话创建接口的去重保证。
Conversation creation and uncertain network results对话创建与未知网络结果
Keep the same UUID request_id when reconciling a conversation creation. The server derives an owner-scoped ID and reads the stored row after an idempotent insert. Do not invent a conversation ID on the client. Goal and memory creation do not yet have equivalent transport deduplication; inspect current records before resubmitting an uncertain operation.核查对话创建时保留相同 UUID request_id。服务端派生用户范围内的编号，在幂等写入后读取已保存记录。客户端不能虚构对话编号。目标与记忆创建尚无同等传输去重；操作结果未知时，应先检查当前记录再决定是否重新提交。
Export, consent and deletion.导出、授权与删除。
Export scope导出范围
GET /api/export returns the authenticated user’s stored conversations with messages, goals with steps, memories and settings. It does not include provider logs, backups, abuse counters or every internal table. The Ari UI labels browser-only history separately.GET /api/export 返回当前用户的已存储对话与消息、目标与步骤、记忆和设置，不包含供应商日志、备份、滥用计数或所有内部表。Ari 界面会单独标明浏览器历史。
Memory consent记忆授权
PUT /api/settings records the long-term-memory preference. Anonymous sessions cannot opt in. When enabled for a registered account, the chat context can include up to five recent saved memories. Turning it off is different from deleting those memories.PUT /api/settings 记录长期记忆偏好，匿名会话不能开启。注册账户开启后，聊天上下文可包含最近五条已保存记忆。关闭记忆与删除记忆是不同操作。
Active database deletion当前数据库删除
DELETE /api/memories deletes owned memory rows; POST /api/auth/delete-account performs account-linked deletion and removes sessions. SQL DELETE is not a claim of physical or cryptographic erasure. Provider backup retention remains unverified.DELETE /api/memories 删除自己的记忆记录；POST /api/auth/delete-account 删除账户关联数据并移除会话。SQL DELETE 不代表物理或密码学抹除，供应商备份保留情况仍未核验。
Read collection, retention and provider limits →阅读收集、保留与供应商限制 →Build, verify, then release.先构建与验证，再发布。
The repository uses npm workspaces. Required local checks run across the existing packages; production releases use the official Wrangler CLI. A successful build does not establish real account or inference behavior.仓库使用 npm workspaces。必需的本地检查覆盖现有包，生产发布使用官方 Wrangler CLI。构建成功不能证明真实账户与推理行为。
npm ci
npm run build
npm run typecheck
npm testBefore publication, record current Worker versions, settings, domains, DNS and bindings. Review a separate preview with isolated test data. After publication, verify the active versions and live domains; preserve the previous version as a rollback candidate. Database rollback is a separate concern from Worker rollback.发布前记录当前 Worker 版本、设置、域名、DNS 与绑定。使用隔离测试数据审查独立预览。发布后核验活动版本与真实域名，并保留旧版本作为回滚候选。数据库回滚与 Worker 回滚是不同事项。