使用 Coding Agent 接入反馈组件
在 Coding Agent 中打开你的项目，然后复制并发送下面的 Prompt。Agent 会检查项目结构，将反馈组件接入现有登录系统，在服务端实现 JWT 签发，并验证接入结果。
不要把 FeedLog SSO 密钥写进 Prompt，也不要粘贴到对话中。Agent 会告诉你如何把密钥配置为服务端环境变量。
复制 Prompt
txt
Integrate the FeedLog feedback widget into this project. Work directly in the current repository: inspect the codebase, make the required changes, run the relevant checks, and verify the integration as far as the available environment allows. Do not stop at providing instructions or example code.
Communicate with me in the language I use. Follow all repository-level instructions, including AGENTS.md, CLAUDE.md, contribution guides, and existing coding conventions.
Official documentation:
- Widget: https://help.feedlog.ai/developers/widget
- SSO and JWT signing: https://help.feedlog.ai/developers/sso
Read the official documentation before editing if network access is available. If it is unavailable, continue using the requirements below. If the current official documentation conflicts with this prompt, follow the documentation and mention the difference in your final report.
## Goal
Complete the full integration:
1. Install and initialize `@feedlog/widget` in the frontend.
2. Connect the widget to the application's existing sign-in state and sign-in UI.
3. Add a server-side endpoint that issues a FeedLog JWT for the current signed-in user.
4. Ensure signed-in users are identified correctly in FeedLog.
5. Ensure signed-out users can enter the application's existing sign-in flow.
6. Keep the FeedLog SSO secret out of browser code, client bundles, logs, and version control.
The widget uses the same JWT format as FeedLog browser SSO, but this task does not require a browser SSO redirect. Do not add a `/api/sso/jwt` handoff or other browser SSO flow unless the project already needs it for a separate reason.
## Inspect the project first
Before asking me for paths or implementation details, inspect the repository and determine:
- the frontend framework, version, package manager, and application entry points;
- where client-only startup code belongs;
- how the frontend reads the current sign-in state;
- how the server authenticates a request and reads the current user;
- where API routes, server actions, or backend handlers belong;
- how environment variables and deployment secrets are managed;
- whether this is a monorepo and where its frontend and backend applications live;
- the existing lint, typecheck, test, build, and browser-test commands.
Reuse the project's existing authentication, API, configuration, and error-handling patterns. Do not introduce a second authentication system or perform an unrelated authentication refactor.
Ask a focused question only when required information cannot be discovered from the repository.
## Handle incomplete repositories safely
The complete integration requires both browser code and a trusted server environment.
If the repository contains only frontend code:
- never sign the JWT in the browser;
- never place the FeedLog SSO secret in a public or client-side environment variable;
- complete only the frontend work that is safe to implement;
- then ask for the backend repository or an existing authenticated endpoint that can issue the FeedLog JWT;
- report the integration as incomplete until the server-side issuer is connected.
If the repository contains only backend code:
- implement the JWT signing function and authenticated token endpoint;
- add the relevant tests;
- ask where the frontend application is located;
- report that widget initialization is still pending.
If both sides are present, complete both without asking for information that the code already provides.
## Install and initialize the widget
Install `@feedlog/widget` with the repository's existing package manager. The package is ESM-only.
Use its public API:
```ts
import { createWidget } from '@feedlog/widget'
createWidget({
baseUrl: feedlogBaseUrl,
auth: {
getToken,
login,
},
theme: 'auto',
})
```
`createWidget` is the package's only export. It has no return value, instance methods, or events. Do not invent or depend on undocumented SDK APIs.
Initialize it only in the browser and once per page. Put the call in the framework's established client-only lifecycle or plugin location. Avoid duplicate initialization during route changes, hot module replacement, or React Strict Mode mounts.
Use the existing application theme when it can be determined reliably. Otherwise use `auto`.
The `baseUrl` must be the URL of the user's FeedLog instance, including the scheme. Reuse existing configuration when present. If it cannot be found, ask me for it. Do not guess a production URL.
## Implement `auth.getToken`
`auth.getToken()` must call an authenticated endpoint in this application. It must have three distinct outcomes:
- return a JWT string when a user is signed in;
- return `null` only when the application has confirmed that no user is signed in;
- throw an error when the request fails, times out, returns an unexpected response, or cannot be parsed.
Do not return `null` for a temporary failure. FeedLog treats `null` as an explicit sign-out and clears the cached widget session.
Do not sign the JWT in browser code.
## Implement `auth.login`
Connect `auth.login()` to the application's existing sign-in experience, such as its current sign-in route, modal, popup, or identity-provider redirect.
Preserve the current page or use the project's existing callback/redirect mechanism when appropriate. Do not create a second sign-in flow for the widget.
`login()` must not settle until the sign-in interaction has finished: for a modal or popup, resolve when it closes; for a full-page redirect, returning immediately is correct because the page navigates away. Returning as soon as the sign-in UI opens leaves the widget signed out until the user clicks sign-in a second time.
The completion of `login()` does not prove that sign-in succeeded. The widget calls `getToken()` again to determine the resulting state, so do not build the integration around a custom success value from `login()`.
## Add the server-side token endpoint
Add an endpoint using the project's existing server API conventions. It must:
1. Authenticate the request with the project's existing server-side session or middleware.
2. Read the user identity from that trusted server-side session.
3. Never trust an email, name, or picture supplied directly by the browser for JWT claims.
4. Return the application's normal signed-out response when there is no current user.
5. Sign and return a FeedLog JWT when a user is signed in.
6. Avoid caching one user's token for another user.
7. Never log the JWT, SSO secret, session cookie, or other credentials.
Use a response shape that fits the existing API conventions. A typical response is:
```json
{
"token": "<signed-jwt>"
}
```
For a signed-out request, the endpoint may return `{ "token": null }` or the project's established unauthenticated status. Make `getToken()` interpret that case as `null` while continuing to throw for temporary and unexpected failures.
## Sign the FeedLog JWT
Sign with HS256 on the server.
Supported claims:
- `email`: required; use the current authenticated user's valid email address;
- `exp`: required; Unix timestamp in seconds;
- `name`: optional;
- `picture`: optional; absolute avatar URL.
Use a one-hour lifetime by default. The expiration must not be more than 24 hours in the future.
For example, the payload should be equivalent to:
```ts
{
email: user.email,
name: user.name,
picture: user.avatarUrl,
exp: Math.floor(Date.now() / 1000) + 60 * 60,
}
```
Omit optional claims when the application does not have reliable values. Do not invent an email address when the current user has none; return a clear, safe error and report the limitation.
Reuse a suitable JWT library already present in the server project when possible. Otherwise add a maintained library compatible with the project's runtime. Do not implement cryptography manually.
## Configure the SSO secret safely
The FeedLog SSO secret is created in:
FeedLog Dashboard -> Developer -> Single Sign-On -> New Secret
Use the secret exactly as the UTF-8 string shown by FeedLog. Do not hex-decode or Base64-decode it before signing.
First check whether an appropriate server-side secret variable already exists, without printing its value. Follow the project's naming convention. If no convention exists, use:
```env
FEEDLOG_BASE_URL=
FEEDLOG_SSO_SECRET=
```
Only the base URL may be exposed to the browser when necessary. `FEEDLOG_SSO_SECRET` must remain server-only and must not use a public prefix such as `VITE_`, `NEXT_PUBLIC_`, `NUXT_PUBLIC_`, or `PUBLIC_`.
If the secret is not configured:
- add the server-side environment-variable declaration and an empty placeholder to the appropriate example environment file;
- do not generate a replacement secret;
- do not ask me to paste the real secret into chat;
- tell me how to create it in FeedLog and place it in the project's local secret store and deployment platform;
- ask me only to confirm when it has been configured.
You may complete code changes, static checks, and tests with a safe test-only secret, but do not claim that the live authentication flow was verified until the real deployment secret is configured. Never put a real secret in a fixture, snapshot, command output, or test log.
## FeedLog dashboard setting
The widget must be enabled in FeedLog Dashboard -> Settings -> Widget. If you cannot perform that external action, continue all repository work and list it as a required manual step.
## Error handling
Handle at least these cases using the project's existing error conventions:
- the user is signed out;
- the signed-in user has no valid email;
- the token endpoint request fails or times out;
- JWT signing fails;
- the FeedLog base URL is missing or invalid;
- the FeedLog SSO secret is missing;
- widget initialization fails.
Errors must not expose the JWT, secret, session cookie, or other credentials.
## Verify the integration
Run the applicable repository checks, including lint, typecheck, tests, and production build. Do not fix unrelated pre-existing failures unless they block this integration; identify them separately.
Add focused tests where the project has an established test setup. Verify as many of these behaviors as the environment allows:
1. A signed-in request receives an HS256 JWT with the correct `email` and `exp`.
2. The JWT expires no more than 24 hours in the future.
3. The user identity comes from the trusted server session, not browser-supplied claims.
4. A confirmed signed-out state makes `getToken()` return `null`.
5. A temporary endpoint or network failure makes `getToken()` throw instead of returning `null`.
6. From a signed-out state, using sign-in inside the widget and completing the application's sign-in flow leaves the widget signed in without a second click.
7. The widget initializes only once in the browser.
8. The SSO secret is absent from client code and the production client bundle.
9. The application builds and loads successfully.
10. When browser testing and a configured FeedLog instance are available, the widget opens and identifies the signed-in user correctly.
Use the repository's approved browser-testing workflow when one exists. If browser verification is not possible, provide exact manual verification steps.
## Definition of done
Report the integration as complete only when:
- the frontend widget is initialized;
- the server-side token endpoint is implemented;
- `getToken()` and `login()` use the existing authentication system;
- the secret remains server-only;
- the relevant automated checks pass;
- live verification is complete, or any external configuration that prevents it is clearly identified.
## Final report
At the end, report concisely:
1. the files changed;
2. where widget initialization lives;
3. where the token endpoint lives;
4. how the current user is read from the server session;
5. the environment-variable names used, without their values;
6. the checks and tests run and their results;
7. the remaining FeedLog Dashboard or deployment steps;
8. anything incomplete or not verified.
Do not finish with only sample code or recommendations. Make the changes in the repository.如果项目缺少必要信息，Agent 可能会询问 FeedLog 地址，或者询问前端、后端代码的位置。你还需要有权限在 FeedLog 控制台中创建 SSO 密钥并启用反馈组件。