From fdec648fdd4b44b2622ad3fe1012342457faf1cb Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Sun, 25 Oct 2026 14:26:24 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(peer):=20=E8=A1=A5=E9=BD=90=E5=A4=9A?= =?UTF-8?q?=E8=BF=9E=E6=8E=A5=E6=89=8B=E5=86=8C=E4=B8=8E=E9=80=82=E7=94=A8?= =?UTF-8?q?=E8=8C=83=E5=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 说明 Web、Mac、浏览器扩展与 CLI 的保存和切换操作 - 明确交互型 Peer 的推荐与固定服务进程的例外 - 保留各入口协议、凭据与已有任务目标边界 --- 10-prd/behavior/capabilities.md | 16 +++ website/.vitepress/config.mts | 1 + website/content/en/developer/architecture.md | 9 ++ website/content/en/guide/connect-cli.md | 4 + website/content/en/guide/connect.md | 20 ++-- website/content/en/guide/connections.md | 113 +++++++++++++++++++ 6 files changed, 151 insertions(+), 12 deletions(-) create mode 100644 website/content/en/guide/connections.md diff --git a/10-prd/behavior/capabilities.md b/10-prd/behavior/capabilities.md index c93f32a..5feaee2 100644 --- a/10-prd/behavior/capabilities.md +++ b/10-prd/behavior/capabilities.md @@ -49,3 +49,19 @@ - related claim(s): organize information in one reusable info-base - non-goal: one runtime does not become the only valid participant in the shared system + +### Peer 本地连接管理（推荐） + +推荐 Peer 支持保存多个命名连接并切换当前连接，让用户在个人、工作或测试信息库之间切换时， +不必反复覆盖地址和凭据。通常需要这一能力的是直接与用户交互的 Peer，例如 Web、桌面应用和 +浏览器扩展。固定部署、持续服务于一个信息库的进程可以只使用部署配置；`impl-py` 的服务器是 +这一例外，不要求提供连接列表或交互式切换。是否需要此能力取决于运行形态，而非实现语言； +同一仓库交付的 CLI 仍可提供本机命名连接。 + +提供多连接的界面应保存列表与当前选择，重新打开后恢复；保留已有单连接，并在切回已保存连接时 +复用其身份。连接名称用于本机辨认，不改变共享 Peer 名称。连接列表和凭据属于各自的本地配置， +不因参与同一信息库而自动同步。不同入口仍使用各自支持的协议和凭据，不能互换地址。 + +切换只改变后续交互的当前目标，不迁移或合并信息库，也不把已经绑定目标的待办或持续收入任务 +改投新库。前台内容须与当前连接一致，不能把旧连接的结果显示为新库内容。后台任务是否继续执行 +由对应能力的生命周期约定决定；切换不能被当作取消旧任务的操作。 diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index 8b4bdd9..eb32937 100644 --- a/website/.vitepress/config.mts +++ b/website/.vitepress/config.mts @@ -99,6 +99,7 @@ export default defineConfig({ link: '/guide/daily-use', items: [ { text: 'Browse and Use Your Information', link: '/guide/daily-use' }, + { text: 'Manage Connections', link: '/guide/connections' }, { text: 'CLI / Agent Connection', link: '/guide/connect-cli' }, { text: 'ChatGPT via MCP', link: '/guide/sinks/chatgpt' }, ], diff --git a/website/content/en/developer/architecture.md b/website/content/en/developer/architecture.md index 2f27a03..9464410 100644 --- a/website/content/en/developer/architecture.md +++ b/website/content/en/developer/architecture.md @@ -66,6 +66,15 @@ Client-web demonstrates this topology: database operations use PostgREST, while capabilities may use native HTTP surfaces advertised by an online Peer. The durable boundary is the admitted protocol and capability contract, not a permanent frontend/backend hierarchy. +Peers that people interact with directly should normally support local named connections and a +current selection. Fixed service processes, including an `impl-py` server deployed for one +info-base, can use a single deployment-configured connection. This recommendation follows the +runtime's use rather than its language or repository: the CLI shipped by `impl-py` has a separate +local connection list. Switching changes the foreground target without moving information or +retargeting work already bound to an instance. The canonical +[Peer connection guidance](https://github.com/InKCre/docs/blob/main/10-prd/behavior/capabilities.md#peer-本地连接管理推荐) +owns the scope; [Manage Connections](/guide/connections) describes the user procedures. + Read the canonical [unit topology](https://github.com/InKCre/docs/blob/main/20-product-tdd/unit-topology.md) and [state authority](https://github.com/InKCre/docs/blob/main/20-product-tdd/system-state-and-authority.md) diff --git a/website/content/en/guide/connect-cli.md b/website/content/en/guide/connect-cli.md index 3a9f961..ccac833 100644 --- a/website/content/en/guide/connect-cli.md +++ b/website/content/en/guide/connect-cli.md @@ -60,4 +60,8 @@ The [CLI reference](https://github.com/InKCre/impl-py/blob/main/cli/README.md) o `--help` explains a command; `--schema` on input-taking commands shows the configuration accepted by your running instance. +For another instance, save a different name instead of overwriting `personal`. See +[Manage Connections](/guide/connections) for switching the default or selecting a connection for one +command. + Next: [Choose your first source](/guide/first-source). diff --git a/website/content/en/guide/connect.md b/website/content/en/guide/connect.md index e2f890e..29a0d1c 100644 --- a/website/content/en/guide/connect.md +++ b/website/content/en/guide/connect.md @@ -19,28 +19,24 @@ the site. 1. Retain your deployment's **PostgREST URL**, private **JWT secret**, and Core URL. 2. Open [Web app Settings](https://app.inkcre.dev/settings). Only enter your secret into a Web app you trust: it grants full deployment authority, not a limited app session. -3. Enter the PostgREST base URL in **PostgreSQL REST URL**, and the secret in **JWT Secret**. Do not - substitute the Core URL for PostgREST. -4. Select **Save** in **Connection**. Language changes take effect separately, without saving the - connection again. +3. Enter a **Connection name**, the PostgREST base URL in **PostgREST URL**, and the secret in **JWT + signing secret**. Do not substitute the Core URL for PostgREST. +4. Select **Save and use connection** in **Connection**. Language changes take effect separately, + without saving the connection again. 5. Open **Peers**. Confirm that **This browser** and Core appear with their application versions. Use **Refresh** after Core starts if its state has not updated yet. 6. To use the public Extension Registry, select **Edit Config** on **This browser**, set `extension_registry_url` to `https://registry.inkcre.dev`, and save. -![Client-web Settings showing connection and local preferences](/images/client-web/settings-overview.png) - -_Settings stores this browser's connection and language. Peer-specific configuration lives under -Peers._ - ![Client-web Peers showing the current browser and Core with their versions and states](/images/client-web/peers-overview.png) _Peers shows the runtimes connected to this deployment. Edit a Peer when configuration belongs to that runtime._ -The connection belongs to this browser origin. To restore it in another browser, use **Export** and -**Import** under **Backup and restore**. Keep the file private: it includes your JWT secret. This -restores browser settings, not a backup of your collected information. +The connection belongs to this browser origin. To add another instance, switch between saved +connections, or move the complete list to another browser, follow +[Manage Connections](/guide/connections). Keep exported settings private: they include the saved JWT +secrets and do not back up collected information. **Checkpoint:** Settings saves successfully and you can open **Sources**. An empty list is normal for a new instance; a connection error is not an empty list. diff --git a/website/content/en/guide/connections.md b/website/content/en/guide/connections.md new file mode 100644 index 0000000..b1803b3 --- /dev/null +++ b/website/content/en/guide/connections.md @@ -0,0 +1,113 @@ +--- +title: Manage Connections +description: Save named connections, switch instances, and keep each interface's target clear. +--- + +# Manage Connections + +Save a connection for each instance you use, such as Personal, Work, or Test. Each interface keeps +its own list and current choice on your device. Reopening it restores that choice. Saving a +connection in the Web app does not configure the Mac app, browser extension, or CLI. + +The procedures below describe versions with saved connections. If your interface has only a single +address field, update it before following the multiple-connection steps. The Mac app is currently +available as a development build. + +## Web app + +First-time setup is covered in [Connect the Web App](/guide/connect). To add another instance: + +1. Open **Settings**, then select **Add connection** under **Connection**. +2. Enter a **Connection name**, **PostgREST URL**, and **JWT signing secret** for that instance. +3. Select **Save and use connection**. The app checks the candidate before saving it as current. +4. Open **Sources** or **Peers** and confirm that you are viewing the intended instance. + +To switch back, choose a saved name in **Current connection**. Switching uses its saved settings and +Peer identity; you do not need to enter them again. To rename or update the current entry, edit its +fields and select **Save and use connection**. Use **Add connection** when the target should remain +a separate entry. + +A failed connection check or save keeps the previously saved selection. If background participation +was stopped during the attempt, use **Retry** or save a working connection to resume it. A failed +switch does not prove that the old background runtime is still running. + +Under **Backup and restore**, **Export** saves all connections, the current choice, and language. +**Import** replaces the browser's list with the imported list and selects its current connection +after validation. Older single-connection backups remain accepted. Export the current list before +importing if you need to keep it. Protect backup files: they contain every saved JWT secret and +restore browser configuration, not the contents of an instance. + +## Mac app + +1. Open **Settings** with `⌘,` and choose **连接** (Connection). +2. Select **添加连接…** (Add connection). Enter a name, PostgreSQL host, port, database, runtime + role, and database password. The optional Web address is used to open shared information in a + browser. +3. Keep TLS certificate verification enabled for remote databases, then select **保存** (Save). +4. Choose the saved name in **当前连接** (Current connection) to switch later. The main window's + Peer page provides the same selector. Use **编辑连接…** (Edit connection) to update the current + entry. + +Mac uses native PostgreSQL and a dedicated admitted runtime role. Its password stays in macOS +Keychain; a Web JWT secret is not a database password. Saving selects the connection and starts a +background check, so a saved entry alone does not confirm connectivity. Inspect the Peer page for +connection errors. + +Existing single-connection settings retain their identity and Keychain reference. Switching back +reuses that identity. Changing the database or runtime role creates a new connection while keeping +the previous entry available. + +Switching clears the foreground directory selection and loads the chosen instance. Already queued +Capture submissions and existing local-directory monitors keep their original targets. They may +continue writing there. To stop a directory's monitoring, switch to its original connection and +pause or remove it separately. + +## Browser extension + +Open the extension's options page. Under **连接** (Connection), select **添加连接** (Add +connection), enter **连接名称** (Connection name) and **API 地址** (API address), then select +**保存并使用连接** (Save and use). Choose a saved name in **当前连接** (Current connection) to +switch. Editing the fields and saving updates the current entry. Other open extension pages observe +the saved choice. + +These entries store the extension's existing compatible HTTP(S) API addresses. Use the endpoint +supported by that extension version; PostgREST and native PostgreSQL addresses are not substitutes. +Saving an address does not check that the remote API is available or change the extension's request +protocol. An existing single API address is retained as the first named entry. + +## CLI and trusted Agents + +The CLI already supports named connections to the Core REST API. Follow +[Connect the CLI](/guide/connect-cli) for installation and initial setup. To add Work alongside +Personal, create a private `work-connection.json` with Work's Core `base_url` and `jwt_secret`, then +run: + +```sh +inkcre-cli connection set work --input work-connection.json +inkcre-cli connection list +inkcre-cli connection use work +inkcre-cli connection check +``` + +`connection use` changes the saved default. To use Personal for just one command without changing +that default: + +```sh +inkcre-cli --connection personal connection check +``` + +Remove the temporary input file when finished and protect the saved +`~/.inkcre/cli/connections.json`, which contains credentials. Connection selection configures the +CLI only; it does not retarget the server it contacts. + +## Keep targets distinct + +Switching does not move or merge information between instances, cancel work already submitted, or +retarget work with a saved destination. Check the current name and address before submitting new +information. Each interface uses its own protocol and credentials even when it reaches the same +information. + +Saved connections are recommended for Peers that people interact with directly. A fixed service +process, such as the `impl-py` server deployed for one instance, normally uses its deployment +configuration and does not need an interactive connection switcher. Its CLI is a separate interface +with its own local connection list. From 55923ee0c4ceb211f55ec26d4d202d6c5fd15f0d Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Mon, 26 Oct 2026 14:25:15 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(mac):=20=E6=98=8E=E7=A1=AE=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=9E=84=E5=BB=BA=E7=9A=84=E6=95=B0=E6=8D=AE=E5=BA=93?= =?UTF-8?q?=E5=89=8D=E6=8F=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 链接原生 Capture 数据库支持，避免误以为现有部署已兼容 --- website/content/en/guide/connections.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/website/content/en/guide/connections.md b/website/content/en/guide/connections.md index b1803b3..894e25a 100644 --- a/website/content/en/guide/connections.md +++ b/website/content/en/guide/connections.md @@ -39,6 +39,11 @@ restore browser configuration, not the contents of an instance. ## Mac app +Mac development builds require the matching +[native Capture database support](https://github.com/InKCre/impl-py/pull/151). Use a database +prepared for that build; a deployment without these database changes cannot accept its Capture +submissions. + 1. Open **Settings** with `⌘,` and choose **连接** (Connection). 2. Select **添加连接…** (Add connection). Enter a name, PostgreSQL host, port, database, runtime role, and database password. The optional Web address is used to open shared information in a