@bizagent/dsh 0.0.0-stage → 1.0.0

package/docs/configuration.md

@@ -0,0 +1,154 @@
+# Configuration
+
+New users can follow the [quick start](quickstart.md) without editing configuration.
+This page is the reference for model connections, custom settings, and data locations.
+
+## Model connection
+
+For another OpenAI-compatible endpoint, use DSH's model settings or add provider rows to
+`$DSH_HOME/profiles/web/cordis.patch.yml` (`DSH_HOME` defaults to `~/.dsh`):
+
+```yaml
+- id: llm-pi-ai
+  config:
+    providers:
+      my-model:
+        displayName: My model
+        apiKeyEnv: MY_MODEL_KEY
+        api: openai-completions
+        baseURL: http://127.0.0.1:8000/v1
+        models:
+          - id: your-model-id
+            name: My model
+            input: [text]
+            contextWindow: 131072
+            maxTokens: 16384
+- id: agent-default-model
+  config:
+    provider: my-model
+    model: your-model-id
+```
+
+Replace the URL, model ID, limits, and modalities with the endpoint's actual capabilities. Provide
+`MY_MODEL_KEY` through DSH's credentials or the environment of a new DSH process. Selecting a
+model in DSH can also save its default; check that default before starting automatic Work.
+
+## Applying changes
+
+Add only the options you change to the profile patch. For example:
+
+```yaml
+- id: bizagent
+  config:
+    timeZone: Europe/Berlin
+    owner: alice
+```
+
+Rows merge over the bundle defaults. DSH Web profiles with HMR can apply profile changes and
+reload changed plugins without restarting the main process. Disabled HMR, headless profiles, or
+host dependency changes may require a planned restart. Let active work settle and inspect DSH's
+reload result rather than assuming an edit has taken effect.
+
+## Plugin options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `homeRoot` | `$BIZAGENT_HOME`, else `~/BizAgent` | BizAgent's data folder: your personal Homes, the pointer to the active organization, and organizations under `orgs/`. Data from before 1.0 at `$DSH_HOME/bizagent` keeps being used until you move it. |
+| `defaultHome` | `personal:default` | Your personal Home: it takes every session that no other Home claims, with or without an organization. |
+| `autoCreateDefaultHome` | `true` | Create `defaultHome` in `homeRoot` on first start. |
+| `defaultIdentity` | (none) | Text for the default Home's `identity.md` when BizAgent creates it. |
+| `owner` | `$BIZAGENT_LOCAL_HUMAN_ID`, else your OS user name | The person who owns Homes BizAgent creates: the default Home, organizations, and Homes added in the panel. |
+| `timeZone` | the host's time zone | IANA zone for cron schedules and daily limits, such as `Asia/Shanghai`. |
+| `workspaceHomes` | `{}` | Extra directories mapped to Homes, as `{ "/path/to/repo": "role:engineering" }`. A session started in a mapped directory binds to that Home, and Work or Inbox wake-ups for that Home start there instead of in its own folder. |
+| `identityMaxBytes` | `6144` | Most bytes of `identity.md` placed in a session's Home snapshot. |
+| `indexMaxBytes` | `16384` | Most bytes of the asset index placed in a session's Home snapshot. |
+| `learningCheckpointEnabled` | `true` | After a turn with an explicit correction, ask the agent once whether to keep it. |
+| `learningSchedulerEnabled` | `false` | Run the `learningSchedules` below. Enable it on one DSH process per profile only. |
+| `learningSchedules` | `[]` | Scheduled learning reviews; see below. |
+
+### Scheduled learning reviews
+
+A schedule starts a separate learning session in a Home when there is unreviewed material:
+
+```yaml
+- id: bizagent
+  config:
+    learningSchedulerEnabled: true
+    workspaceHomes:
+      /home/alice/work/analytics: role:analytics
+    learningSchedules:
+      - home: role:analytics
+        cron: '0 3 * * *'      # every day at 03:00 in timeZone
+        model: deepseek-flash  # add provider: <id> to pick a provider
+        dailyRuns: 1           # 1 to 4
+```
+
+Each scheduled Home needs exactly one directory in `workspaceHomes`. The Home's page under
+**Learning** then shows the schedule; its owner can pause it or change the time and daily runs
+within the limits above.
+
+## Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `BIZAGENT_HOME` | BizAgent's data folder when `homeRoot` is not set (default `~/BizAgent`). Isolated runs set it next to their own `DSH_HOME`. |
+| `DSH_HOME` | DSH's data directory (default `~/.dsh`). Holds sessions and BizAgent's ledgers. |
+| `BIZAGENT_LOCAL_HUMAN_ID` | Your user id for owning Homes and reviewing, if it should differ from your OS user name. Letters, digits, `.`, `_`, `-`. |
+| `BIZAGENT_LOCAL_HUMAN` | Set to `off` to disable the local review routes (Project acceptance, proposal decisions, My Inbox). |
+| `BIZAGENT_LOCAL_HUMAN_TOKEN_FILE` | A private (mode 0600) file holding a 32 to 512 character token. Scripts can then call the review routes with `Authorization: Bearer <token>`. Not needed in the browser. |
+| `BIZAGENT_LOCAL_PLATFORM_ADMIN` | Set to `1` to let the local owner review platform-wide shared Knowledge. |
+
+## Local review
+
+The `bizagent-local-human` plugin row (inserted by BizAgent's bundle) serves the routes behind
+**Accept result**, proposal decisions, and **My Inbox**. In the DSH web app the person signed in
+to DSH is the reviewer, acting as `owner`, so nothing needs to be set up. These routes only run
+when DSH Web listens on `127.0.0.1`, which is the DSH default.
+
+To accept a Project from a script, set `BIZAGENT_LOCAL_HUMAN_TOKEN_FILE` before starting DSH and
+send the token:
+
+```sh
+curl -X POST 'http://127.0.0.1:<port>/api/bizagent/project-review' \
+  -H "Authorization: Bearer $(cat ~/.config/bizagent/human.token)" \
+  -H "Origin: http://127.0.0.1:<port>" -H 'Content-Type: application/json' \
+  -d '{"projectId":"<id>","claimId":"<claim>","expectedRevision":3,"decision":"accept","reason":"Checked."}'
+```
+
+`GET /api/bizagent/project-review?projectId=<id>` with the same header returns the current claim
+id and revision.
+
+## Data and backups
+
+- Home files live in `~/BizAgent` (or `homeRoot` / `BIZAGENT_HOME`): your outside personal Homes
+  under `homes/`, and organization Homes under `orgs/<id>/homes/`. A Home folder is also its
+  normal chat/worker directory, unless an explicit workspace mapping is configured.
+- Bindings, proposals, Inbox, Work, Projects, and Worklogs live in DSH storage under `DSH_HOME`.
+  Original conversations are DSH sessions. Retained artifact snapshots belong to the Home's data space.
+
+An organization directory alone is not a full backup. Preserve both the Home data and the matching
+DSH data. The Home archive commands verify the file portion; from `packages/dsh`:
+
+```sh
+BIZAGENT_ORG_ROOT="$HOME/BizAgent/orgs/your-organization"
+node lib/cli.js --root "$BIZAGENT_ORG_ROOT" archive export ./homes-backup
+node lib/cli.js archive verify ./homes-backup
+```
+
+One organization is active at a time. There is no general organization-switching UI in this
+version. Keep the current organization when trying practice Homes; do not delete its directory
+or active pointer as an onboarding step. For a separate sandbox, use new, matching `DSH_HOME`
+and `BIZAGENT_HOME` directories and leave the existing instance intact.
+
+## Hosts with their own login
+
+Embedding BizAgent in another host, with real user accounts or notification channels, uses the
+building blocks exported from `@bizagent/dsh/host`: route handlers for Project review, proposal
+review, shared Knowledge review, and the human Inbox, each taking your own authentication and
+authorization callbacks; runners for notifications and stalled conversations; and Home archive
+export, verify, and import. Disable the local review row when you mount your own:
+
+```yaml
+- id: bizagent-local-human
+  disabled: true
+```

package/docs/quickstart.md

@@ -0,0 +1,103 @@
+# Install and first success
+
+[文档导航 / Documentation](README.md) · English | [中文](quickstart.zh-CN.md)
+
+Already using BizAgent? Skip to [Use BizAgent](#use-bizagent).
+This page gets you to one saved rule; configuration and architecture can wait.
+
+## Install
+
+Use Node.js 24+ or 22.19+ on the 22.x line, and pnpm 11. The commands below pin the DSH version
+used in the manual browser acceptance run. Existing DSH users should first check `dsh --version`;
+there is no need to replace a working installation just to try the plugin.
+
+```sh
+# Only if DSH / pnpm is not installed:
+npm install --global @deepseek-ai/dsh@0.2.1-rc.2 pnpm@11
+
+git clone https://github.com/phonism/bizagent.git
+cd bizagent/packages/dsh
+npm ci
+npm run build
+BIZAGENT_PACKAGE=$(npm pack --silent)
+dsh plugin --profile web add "$PWD/$BIZAGENT_PACKAGE"
+```
+
+Installation, development dependencies, and CI use DSH `0.2.1-rc.2`, the same version used for
+manual browser acceptance. See
+[Verification](verification.md). Install into the same profile and `DSH_HOME` you intend to run.
+
+## Connect a model and open DSH
+
+For a new DSH process, configure the default DeepSeek provider before starting it:
+
+```sh
+export DEEPSEEK_API_KEY=sk-...
+dsh --profile web
+```
+
+If DSH is already running, use its model/credential settings; exporting a variable in a new
+terminal does not change the running process. The model must support tool calling and have room
+for DSH's tools plus BizAgent's 59 tools. Other OpenAI-compatible endpoints are covered in
+[Configuration](configuration.md#model-connection).
+
+Open the login URL DSH prints in the terminal. **BizAgent organization** should appear in the
+sidebar. If adding a plugin to a running profile, let DSH apply the profile change and refresh
+the page. Consult the startup errors if the entry is missing; [troubleshooting](#troubleshooting)
+does not require deleting existing data.
+
+## Save your first rule
+
+No organization is required:
+
+1. Open **BizAgent organization → Learning → My personal Home → Chat**.
+2. Send:
+
+   > Remember this practice-only rule in this Home: for the fictional onboarding orders, GMV
+   > includes paid orders and excludes cancelled and refunded orders. Save it, then tell me its
+   > asset ID and status. Do not apply it as a real business policy.
+
+3. Click the Home in the conversation header, or return to **Learning**. Expand the saved asset
+   and check its body, source, and status. A success message in chat alone is not enough.
+4. If it is `active`, start another DSH session **in that Home's workspace** and ask it to read
+   the saved rule. Check the new session's Home. Clicking **Chat** again reopens the same
+   Principal; it does not create a fresh session.
+
+A `candidate` is saved for review but stays out of the default active index. Ask the agent to
+review its evidence before publishing it. New sessions receive an asset index, not every full body.
+
+## Use BizAgent
+
+| What you want | Where to go | What to check |
+| --- | --- | --- |
+| Recall or inspect a rule | Home button → Learning | Body, evidence, active/candidate status |
+| Borrow shared knowledge | Pick a shared Home from the composer's `@` suggestions | Frame bar; no independent worker is launched |
+| Give another agent a deliverable | Ask for formal Work; open **Work & learning** | Assignee, work status, **View worker Session**, result |
+| Accept a Project | Open the Project from **Work & learning**, or **Projects → My review queue** | Submitted claim, evidence, review reason, **Accept result** |
+| Reply to an agent | **My Inbox** | Send a reply; check it returns to the originating session |
+
+If no organization exists, **Create sample team** builds Sample Shop with a guide and an
+`orders.csv`. Follow its four steps: teach the analyst a rule, ask the lead to create a Project,
+open the Project's separate chat to dispatch Work, then inspect and accept its result. The sample
+excludes cancelled/refunded orders and includes `shipped`: **120.50 + 45.25 + 200 + 34.75 = 400.50**.
+You can then propose the rule to the Sample Shop Home and review it in Learning.
+
+If an organization already exists, keep it. Open **Learning → Create Home** for practice agents,
+or use your existing members. The [Chinese user guide](user-guide.zh-CN.md) supplies an isolated
+four-order exercise with an expected total of **300**, including exact prompts and checkpoints.
+To build your own organization on a fresh setup, choose the organization wizard instead of the sample.
+
+## Troubleshooting
+
+| Symptom | First check |
+| --- | --- |
+| `pnpm was not found` | Install pnpm 11 and check it is on the DSH process's PATH. |
+| No BizAgent sidebar entry | Confirm profile / `DSH_HOME`; inspect activation errors and the [tested versions](verification.md). |
+| Writer already reserved | Check which process owns the data. Use a separate `DSH_HOME` **and** `BIZAGENT_HOME` for a sandbox; do not stop an unknown process. |
+| Rule is missing | Check the Home, filters, and `candidate` status; inspect the save tool result. |
+| No independent worker | Inspect Work status and launch errors; automatic execution requires the same owner. A Frame does not dispatch Work. |
+| No Project or acceptance button | Return to the lead/project session, or use **My review queue**; verify login, ownership, a pending claim, and a filled review reason. |
+| Wrong example total | Sample Shop is 400.50; the four-order exercise is 300. They use different orders and rules. |
+
+Next: [Concepts](concepts.md) for the ownership model; [Configuration](configuration.md) for
+custom settings, data locations, and backup scope.

package/docs/quickstart.zh-CN.md

@@ -0,0 +1,86 @@
+# 安装与首次成功
+
+[文档导航](README.md) · 中文 | [English](quickstart.md)
+
+已经能打开 BizAgent？直接进入[用户指南](user-guide.zh-CN.md)。这一页只带你完成安装并确认一条记忆真正保存成功。
+
+## 安装
+
+准备 Node.js 24 及以上，或 22.19 及以上的 22.x，以及 pnpm 11。
+已有 DSH 时先运行 `dsh --version`，跳过全局安装命令，保留正在工作的环境。
+
+```sh
+# 仅在未安装 DSH / pnpm 时执行：
+npm install --global @deepseek-ai/dsh@0.2.1-rc.2 pnpm@11
+
+git clone https://github.com/phonism/bizagent.git
+cd bizagent/packages/dsh
+npm ci
+npm run build
+BIZAGENT_PACKAGE=$(npm pack --silent)
+dsh plugin --profile web add "$PWD/$BIZAGENT_PACKAGE"
+```
+
+安装、开发依赖和 CI 统一使用 DSH `0.2.1-rc.2`，与真实浏览器验收版本一致。
+验证范围见[兼容与验证](verification.md)。
+安装和启动需要使用同一个 profile、同一个 `DSH_HOME`；默认是 `web` 和 `~/.dsh`。
+
+## 连接模型并启动
+
+新启动的 DSH 默认使用 DeepSeek；先设置自己的 Key，再启动：
+
+```sh
+export DEEPSEEK_API_KEY=sk-...
+dsh --profile web
+```
+
+已经运行的 DSH 请在模型/凭据设置中配置；在新终端 `export` 不会改变已有进程的环境。
+模型需要支持工具调用，并能容纳 DSH 自带工具及 BizAgent 的 59 个工具。
+其他 OpenAI 兼容模型的配置见[配置参考](configuration.md#model-connection)。
+
+打开终端打印的登录链接。侧边栏应出现 **BizAgent 组织**。
+给运行中的 profile 安装插件后，等待 DSH 应用变更并刷新页面；入口未出现时先看终端的插件加载错误。
+
+## 第一次成功：存下一条规则
+
+不用先建组织，也不用先理解所有概念。
+
+1. 点 **BizAgent 组织 → 学习 → 我的个人 Home → 对话**。
+2. 发送：
+
+   > 请在当前 Home 记住一条仅用于上手练习的规则：虚构订单的 GMV 只计 paid，排除 cancelled 和 refunded。
+   > 请实际保存，并告诉我资产编号和状态。不要把它当成真实业务规则。
+
+3. 点会话顶部的 Home，回到「学习」，展开这条资产，检查**正文、证据来源和状态**。
+   Agent 口头说“记住了”不足以证明保存成功。
+4. 若状态为 `active`，在**同一个 Home 工作区**中新建 DSH 会话，请它读取刚保存的规则。
+   核对新会话顶部的 Home；再点「对话」会重新打开原来的主会话，不算新会话验证。
+
+**成功标志**：学习页有这条规则及来源，新会话实际读取了它。
+若是 `candidate`，先让 Agent 核对证据再发布；候选内容不会进入默认生效索引。
+新会话默认拿到索引，需要使用规则时再读取正文。
+
+## 下一步怎么走
+
+| 当前情况 | 建议下一步 |
+| --- | --- |
+| 只需要个人记忆 | 继续在自己的 Home 工作，按需查看、修订经验 |
+| 首次设置，想体验团队 | 在「组织」点「创建示例团队」，跟随页面向导；内置订单结果为 400.50 元 |
+| 已有组织，想试协作 | 按[用户指南](user-guide.zh-CN.md)创建两个练习 Home，完成 300 元订单练习 |
+| 想直接建自己的团队 | 在首次组织向导填写使命、成员和共享能力，再从各 Home 的「对话」进入 |
+
+已有组织时保留它，不必删除目录来重跑向导。
+
+## 遇到问题时
+
+| 现象 | 先检查 |
+| --- | --- |
+| 找不到 pnpm | pnpm 11 是否在 DSH 进程的 PATH 中 |
+| 侧边栏没有 BizAgent | profile、`DSH_HOME`、终端加载错误，以及[已验证版本](verification.md) |
+| 提示 writer 已占用 | 确认数据由哪个进程使用；独立试用同时设置新的 `DSH_HOME` 和 `BIZAGENT_HOME`，不要结束不明进程 |
+| 看不到新记忆 | 是否选对 Home、是否被筛选隐藏、是否为 candidate；检查保存工具结果 |
+| 分析师没有运行 | 「工作与经验」的 Work 状态与启动错误；自动执行要求双方 owner 相同；`@` 引用只提供上下文 |
+| 找不到项目或验收按钮 | 返回负责人/项目会话，或从「我的审核待办」查找；确认已登录、具备权限、有待验收提交，并填了理由 |
+| GMV 与教程不一致 | 内置示例为 400.50 元；独立的四笔订单练习为 300 元，不能混用口径 |
+
+下一页：[用户指南](user-guide.zh-CN.md)，按界面完成独立派工、查看交付和人工验收。