docs: rewrite public README for open-source users

2178 · 2178 · commit b4a4932975a0 · 2026-07-08T16:39:15.000+08:00
Rewrite the project README as a normal open-source entrypoint:
- explain purpose, use cases, benefits, install options, and requirements
- add quick-start examples for core metadata, RunningHub descriptors, client usage, and key-pool helpers
- clarify what the kit does and does not provide
- link documentation, development commands, harness rules, security, contribution, and license information

Also record the README update and verification result in the daily log.
diff --git a/README.md b/README.md
@@ -1,23 +1,56 @@
 # AIGC Provider Runtime Kit
 
-Reusable TypeScript runtime primitives for AIGC products that need to manage multiple model providers and RunningHub entries without rebuilding the same provider configuration layer for every project.
+[![CI](https://github.com/Hhh2178/aigc-provider-runtime-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Hhh2178/aigc-provider-runtime-kit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
 
-![CI](https://github.com/Hhh2178/aigc-provider-runtime-kit/actions/workflows/ci.yml/badge.svg)
+Framework-neutral TypeScript primitives for AIGC products that need to manage model providers, model parameters, request bodies, RunningHub Apps/Workflows, and provider key concurrency without rebuilding the same runtime layer in every project.
 
-This project starts as a small, framework-neutral kit extracted from production lessons:
+This repository is a small runtime kit, not a hosted service. It gives your application typed building blocks; your application keeps ownership of credentials, databases, queues, permissions, billing, and auditing.
 
-- Provider protocol and model capability types.
-- Model parameter schema and UI metadata helpers.
-- JSON and multipart request body helpers.
-- RunningHub App / Workflow catalog types.
-- RunningHub execution descriptor generation.
-- RunningHub submit / poll client.
-- RunningHub key-pool concurrency dispatch.
-- Project harness docs and verification contracts for long-term maintenance.
+## Why This Exists
 
-## Status
+Most AIGC applications eventually need the same provider infrastructure:
 
-`v0.1.0` is a foundation release. APIs are intentionally small and may evolve before a stable `1.0`.
+- A normalized way to describe providers and models.
+- Model parameter schemas that can drive admin forms, canvas nodes, or API payloads.
+- Request body helpers for JSON and multipart provider APIs.
+- A reusable RunningHub App/Workflow catalog model.
+- A safe way to submit, poll, and extract media outputs from RunningHub tasks.
+- Key-pool helpers so multiple API keys can be used without exceeding concurrency limits.
+
+`aigc-provider-runtime-kit` packages those common pieces as reusable TypeScript modules.
+
+## Features
+
+- **Provider contracts**: typed provider, model, capability, and parameter schema definitions.
+- **UI-ready model metadata**: convert schemas into aspect ratio, size, duration, resolution, and reference-input metadata.
+- **Request body helpers**: build multipart `FormData` payloads from scalar fields, remote URLs, or data URLs.
+- **RunningHub catalog helpers**: normalize RunningHub App/Workflow records into reusable host-app entries.
+- **Execution descriptors**: generate submit/poll/output handling metadata for RunningHub tasks.
+- **RunningHub client**: submit tasks, poll results, normalize failures, and extract image/video/audio URLs.
+- **Key-pool concurrency**: acquire and release RunningHub keys against a Redis-like runtime interface.
+- **No framework lock-in**: works with Node.js services, workers, CLI tools, or any framework that can import ESM.
+- **Governed project harness**: includes docs, CI, tests, and verification scripts to keep the package maintainable.
+
+## Install
+
+```bash
+npm install aigc-provider-runtime-kit
+```
+
+The package is currently in the `0.1.x` foundation line. APIs are intentionally small and may evolve before `1.0`.
+
+If the package has not been published to npm in your environment yet, install directly from GitHub:
+
+```bash
+npm install github:Hhh2178/aigc-provider-runtime-kit
+```
+
+## Requirements
+
+- Node.js 22 or a modern runtime with ESM, `fetch`, `FormData`, `Blob`, and `AbortSignal.timeout`.
+- TypeScript is recommended for the best developer experience.
 
 ## Package Entrypoints
 
@@ -28,85 +61,216 @@ This project starts as a small, framework-neutral kit extracted from production
 | `aigc-provider-runtime-kit/runninghub` | RunningHub catalog, descriptor, client, and key-pool helpers |
 | `aigc-provider-runtime-kit/runtime` | Explicit combined runtime exports |
 
-## Install
+## Quick Start
 
-```bash
-npm install aigc-provider-runtime-kit
-```
+Create UI-friendly model metadata from a provider model:
 
-Until the package is published to npm, consume the GitHub repository directly or copy the packages into an internal workspace.
+```ts
+import {
+  defaultParameterSchemaForModel,
+  uiMetadataFromSchema
+} from "aigc-provider-runtime-kit/core";
 
-## Quick Example
+const schema = defaultParameterSchemaForModel("image", "gpt-image-2", "openai");
+const ui = uiMetadataFromSchema(schema, "image");
+
+console.log(ui.defaultAspectRatio);
+console.log(ui.maxReferenceImages);
+```
+
+Build a RunningHub execution descriptor:
 
 ```ts
-import { defaultParameterSchemaForModel } from "aigc-provider-runtime-kit/core";
 import { buildRunningHubExecutionDescriptor } from "aigc-provider-runtime-kit/runninghub";
 
-const schema = defaultParameterSchemaForModel("image", "gpt-image-2", "openai");
-
 const execution = buildRunningHubExecutionDescriptor({
-  kind: "app",
-  appId: "rh-app-id",
-  runTargetId: "rh-app-id",
-  taskCapability: "image",
-  fields: []
+  kind: "workflow",
+  workflowId: "workflow-id",
+  runTargetId: "workflow-id",
+  taskCapability: "video",
+  fields: [
+    {
+      nodeId: "6",
+      fieldName: "prompt",
+      label: "Prompt",
+      valueType: "string",
+      required: true
+    }
+  ]
+});
+
+console.log(execution.submit.submitMode);
+console.log(execution.polling.intervalMs);
+```
+
+Submit and poll a RunningHub task from your worker:
+
+```ts
+import { createRunningHubClient } from "aigc-provider-runtime-kit/runninghub";
+
+const client = createRunningHubClient({
+  apiKey: process.env.RUNNINGHUB_API_KEY!,
+  baseUrl: "https://www.runninghub.cn"
 });
+
+const result = await client.runTask({
+  targetType: "workflow",
+  runTargetId: "workflow-id",
+  workflowId: "workflow-id",
+  nodeInfoList: [
+    {
+      nodeId: "6",
+      fieldName: "prompt",
+      fieldValue: "A cinematic robot walking through a rainy neon street"
+    }
+  ],
+  timeoutMs: 10 * 60 * 1000
+});
+
+console.log(result.videoUrls);
+```
+
+Use key-pool helpers with a Redis-like runtime:
+
+```ts
+import {
+  acquireRunningHubKey,
+  releaseRunningHubKey
+} from "aigc-provider-runtime-kit/runninghub";
+
+const acquired = await acquireRunningHubKey({
+  providerId: "runninghub",
+  defaultConcurrency: 2,
+  runtime: redisLikeRuntime,
+  keys: [
+    {
+      id: "key-1",
+      note: "primary",
+      apiKey: process.env.RUNNINGHUB_API_KEY,
+      maxConcurrency: 2,
+      enabled: true,
+      isDefault: true
+    }
+  ]
+});
+
+if (!acquired.acquired) {
+  throw new Error(`No RunningHub key available: ${acquired.reason}`);
+}
+
+try {
+  // Run provider task with acquired.key.apiKey.
+} finally {
+  await releaseRunningHubKey({
+    providerId: "runninghub",
+    keyId: acquired.key.id,
+    runtime: redisLikeRuntime
+  });
+}
 ```
 
-More examples:
+## What You Can Build With It
 
-- `docs/getting-started.md`
-- `docs/api-reference.md`
-- `examples/node-basic/`
+- A multi-provider AIGC backend.
+- A provider/model management admin panel.
+- A visual canvas node runtime for image, video, audio, or workflow generation.
+- A RunningHub App/Workflow gateway.
+- A worker service that dispatches provider jobs with API key concurrency limits.
+- A shared provider runtime layer reused across multiple products.
+
+## What This Kit Does Not Do
+
+- It does not store API keys or credentials.
+- It does not provide a hosted API service.
+- It does not include a database schema or migration system.
+- It does not implement user permissions, billing, or quota policies.
+- It does not ship an admin UI.
+- It does not hide RunningHub or provider-specific business rules from your host application.
+
+## Recommended Architecture
+
+```text
+Your app/admin UI
+  -> your database and permission model
+  -> your job queue or worker
+  -> aigc-provider-runtime-kit
+  -> provider APIs such as RunningHub or OpenAI-compatible services
+```
+
+Keep secrets and user permissions in your application. Use this package to normalize provider definitions, request contracts, task execution metadata, result extraction, and key-pool coordination.
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md)
+- [API Reference](./docs/api-reference.md)
+- [Roadmap](./docs/roadmap.md)
+- [Provider System Notes](./docs/systems/providers/README.md)
+- [RunningHub System Notes](./docs/systems/runninghub/README.md)
+- [Project Harness Notes](./docs/systems/harness/README.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security Policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
 
 ## Repository Layout
 
 ```text
 packages/core/        Provider, model, schema, and request body primitives
 packages/runninghub/  RunningHub catalog, descriptor, client, and key-pool helpers
 packages/runtime/     Combined public exports
-docs/                 Harness, governance, system docs, specs, and plans
-scripts/              Local verification contracts
 examples/             Minimal usage examples
 tests/                Node built-in test coverage for public behavior
+docs/                 Harness, governance, system docs, specs, and plans
+scripts/              Local verification contracts
 .github/workflows/    GitHub CI verification
 ```
 
-## Harness
-
-This repository uses a lightweight doc-log harness:
-
-- `AGENTS.md` is the AI agent constitution.
-- `docs/INDEX.md` is the documentation router.
-- `docs/systems/` owns system contracts.
-- `docs/logbooks/` records audit evidence.
-- `scripts/verify-harness.mjs` checks required project anchors.
-
-Run:
+## Local Development
 
 ```bash
+npm ci
 npm run harness:verify:project
 npm run type-check
+npm run build
 npm test
 ```
 
-## Local Development
+Use the full release gate before publishing or tagging:
 
 ```bash
-npm ci
-npm run harness:verify:project
-npm run type-check
-npm run build
-npm test
+npm run harness:verify:release
 ```
 
-## Public Project Docs
+## Harness
 
-- `CONTRIBUTING.md` explains contribution flow and commit boundaries.
-- `SECURITY.md` defines vulnerability and secret-handling rules.
-- `CHANGELOG.md` records public release changes.
-- `docs/roadmap.md` tracks the foundation roadmap without promising hosted infrastructure.
+This repository uses a lightweight doc-log Harness so future maintainers and AI agents can understand and verify changes without guessing:
+
+- `AGENTS.md` is the agent constitution.
+- `docs/INDEX.md` is the documentation router.
+- `docs/systems/` owns system contracts.
+- `docs/logbooks/` records audit evidence.
+- `scripts/verify-harness.mjs` checks required project anchors.
 
 ## Security
 
-Never commit provider API keys, RunningHub keys, `.env` files, server credentials, or real customer configuration. This kit should contain reusable contracts and code only.
+Never commit provider API keys, RunningHub keys, `.env` files, private keys, server credentials, customer data, or real production configuration.
+
+Host applications are responsible for:
+
+- Secret storage.
+- Permission checks.
+- Provider quotas.
+- Audit logs.
+- Network egress controls.
+- Incident response.
+
+See [SECURITY.md](./SECURITY.md) for details.
+
+## Contributing
+
+Contributions are welcome. Please keep changes small, typed, tested, and framework-neutral. If you change public exports or runtime behavior, update the API reference and relevant system docs.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
diff --git a/docs/logbooks/daily/2026/2026-07/2026-07-08.md b/docs/logbooks/daily/2026/2026-07/2026-07-08.md
@@ -70,3 +70,34 @@ Upgrade the repository from an internal extraction scaffold into a more complete
 ## Next
 
 Run verification, fix any failures, then commit and push the standalone project maturity update.
+
+---
+
+## Intent
+
+Rewrite the public README for external GitHub users so the project reads like a normal open-source package instead of an internal extraction note.
+
+## Changed
+
+| Area | Files | Purpose |
+| --- | --- | --- |
+| Public project entry | `README.md` | Add open-source positioning, feature list, install paths, requirements, quick starts, architecture guidance, docs map, local development, harness, security, contributing, and license sections |
+
+## Verification
+
+| Check | Result | Notes |
+| --- | --- | --- |
+| `npm run harness:verify:project` | Passed | README still satisfies required public project anchors |
+
+## Decisions
+
+- Use English for the public README because the GitHub project is intended for broader external reuse.
+- Keep README focused on reusable runtime value and avoid claiming this package is a hosted backend or full admin system.
+
+## Risks
+
+- GitHub badge depends on the repository workflow path remaining `.github/workflows/ci.yml`.
+
+## Next
+
+Run harness verification, commit, and push the README improvement.
